{
  "openapi": "3.1.0",
  "info": {
    "title": "AudioSilo Meta API",
    "version": "1.0.0",
    "summary": "The API over the AudioSilo community audiobook metadata database.",
    "description": "An API over a compiled snapshot of the community metadata database at https://github.com/kodestar/audiosilo-meta.\n\nEverything in the catalogue is public: no authentication and no API key, and no endpoint changes it. (A production deployment may additionally register a release-notification hook at `/hooks/github/release`, which is HMAC-authenticated, and an intake queue, which takes anonymous reports of ASINs the catalogue does not hold and gives them back behind a bearer token. Neither is part of the read surface. A deployment's own `/api/v1/openapi.json` lists only the intake routes it serves, and the published reference built from this file lists them all.)\n\nThe API surface - `/api/v1/*` and `/abs/search` - carries permissive CORS headers (`Access-Control-Allow-Origin: *`), so a browser may call it directly. `/healthz`, the hook and the intake routes do not.\n\nThe API surface is rate limited per client address (a token bucket; the public deployment allows 100 requests a second with a burst of 400; an IPv6 client counts as its /64). A client past its allowance gets `429` with a `Retry-After` header in whole seconds and the error envelope; `/healthz` is exempt. A successful answer carries a `Cache-Control` header when its route states none of its own: `public, max-age=600`, or `public, max-age=60` on the searches and `/api/v1/works/match`. A reader that wants the whole catalogue should download the `meta.sqlite.gz` asset of the newest data release instead of paging the API.\n\nThe server holds one compiled artifact at a time and swaps in a newer one without a restart, so a response is always a consistent view of a single release. While no artifact has loaded yet (a cold boot still fetching the newest release) every data route answers `503` with a `Retry-After` header; `/api/v1/openapi.json` and the static site are served regardless.\n\nSome fields on `GET /works/{id}` depend on the loaded artifact's internal schema version - characters and recaps need version 2, the whole-book recap summary version 3, genres version 4, the community description version 6. A recording's optional `abridgement` preserves stated unabridgement from artifact version 13; absence means unknown, including legacy false on older artifacts. The languages layer needs version 7: the translation links on works and series, a series' derived `language`, `ordering`, `ordering_of` and `orderings`, the `ordering_of` on a series membership and the `languages` census on `/api/v1/stats`. The LibriVox layer needs version 8: a recording's `librivox_id`, `archive_id`, `links` and `copyright_year`, a chapter's `audio_url`, the free `librivox` purchase link, the `source` filter, `lookup?librivox_id=` and the LibriVox-shaped feed (which answers `404` on an older artifact, as it does for no results). A server briefly serving an older artifact omits them rather than failing, so treat every one of them as optional.\n\nSlugs are stable, and a slug a data-quality repair RETIRES keeps resolving: every route that takes an id answers `301` with a `Location` at the same route under the slug that replaced it, plus a body naming that slug so a stored id can be healed. The redirect is bounded by `Cache-Control` rather than permanent, because reversing a merge withdraws it. Redirects need artifact version 5; below it a retired slug is a `404`.\n\nLicensing: the factual core (works, recordings, people, series) is dedicated to the public domain under CC0-1.0 and the community layer (characters, recaps, descriptions) is CC BY-SA 4.0 - see LICENSING.md in the repository for what attribution the share-alike layer requires.",
    "license": {
      "name": "CC0-1.0 core with a CC BY-SA 4.0 community layer",
      "url": "https://github.com/kodestar/audiosilo-meta/blob/main/LICENSING.md"
    }
  },
  "servers": [
    {
      "url": "https://meta.audiosilo.app",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "audiosilo-meta on GitHub",
    "url": "https://github.com/kodestar/audiosilo-meta"
  },
  "tags": [
    {
      "name": "Search",
      "description": "Full-text search over the catalogue. One combined endpoint returning works, people and series together, plus three type-scoped variants returning a single kind."
    },
    {
      "name": "Works",
      "description": "Work documents: the abstract book, its recordings, and the community expressive layer."
    },
    {
      "name": "People & Series",
      "description": "A person's credits and a series' member works, both windowed with unpaged totals."
    },
    {
      "name": "Lookup",
      "description": "Exact identifier resolution: which recording an ASIN, ISBN or LibriVox project id names."
    },
    {
      "name": "LibriVox",
      "description": "The LibriVox mirror: the public-domain LibriVox catalogue, held as ordinary works and recordings in this database, answered in the shape of LibriVox's own audiobooks feed so an app that reads LibriVox can move here by changing its base URL."
    },
    {
      "name": "Coverage",
      "description": "What the community layer still needs: expressive-layer totals, a filtered per-work browser, and series with missing volumes."
    },
    {
      "name": "Watch feeds",
      "description": "Stateless notification feeds for a list of series carried in the request URL, as Atom, JSON Feed or a subscribable release calendar."
    },
    {
      "name": "Audiobookshelf provider",
      "description": "The Audiobookshelf custom metadata provider facade. It lives outside /api/v1 because Audiobookshelf appends /search to a configured base URL, and it speaks Audiobookshelf's BookMetadata shape rather than this API's."
    },
    {
      "name": "Server",
      "description": "Readiness, catalogue totals, this document, and the routes only a deployment that configures them serves: the release-notification hook and the intake queue."
    }
  ],
  "paths": {
    "/healthz": {
      "get": {
        "tags": ["Server"],
        "operationId": "healthz",
        "summary": "Readiness probe",
        "description": "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.",
        "responses": {
          "200": {
            "description": "An artifact is loaded and the API is answering.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Health" }
              }
            }
          },
          "503": {
            "description": "No artifact has loaded yet. `Retry-After` reports the wait the poll loop is actually on.",
            "headers": {
              "Retry-After": { "$ref": "#/components/headers/RetryAfter" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthStarting" }
              }
            }
          }
        }
      }
    },
    "/api/v1/openapi.json": {
      "get": {
        "tags": ["Server"],
        "operationId": "openapi",
        "summary": "This document",
        "description": "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.\n\nThe 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.",
        "responses": {
          "200": {
            "description": "The OpenAPI 3.1 document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "An OpenAPI 3.1 document."
                }
              }
            }
          },
          "304": {
            "description": "The `If-None-Match` request header named the current `ETag`, so the copy the client holds is still the document. No body."
          }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "tags": ["Server"],
        "operationId": "stats",
        "summary": "Catalogue totals",
        "description": "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.",
        "responses": {
          "200": {
            "description": "The loaded artifact's totals.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Stats" }
              }
            }
          },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "tags": ["Search"],
        "operationId": "search",
        "summary": "Search works, people and series together",
        "description": "One ranked page mixing all three kinds, ordered by full-text relevance. Every result carries a `kind` discriminator.\n\nMatching 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\".\n\nTwo 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. A query that IS a series' name ranks that series first among the page's series rows, the primary series ahead of same-named translations and reading-order variants (see `searchSeries`); those rows take the place of the page's first series row, and every other row keeps its relative order. Series on the page sharing one name are ordered the same way within the places they already hold, so a half-typed \"harry pot\" lists the primary first among them too. A window smaller than the relevance tie may hold same-named translations or variants and not their primary; when those rows name it (`translation_of`, `ordering_of`) under the same name, it is pulled onto the page and ranked ahead of them, even beside an unrelated series of that name, so a linked same-named primary can appear although the relevance window did not hold it - never one outside `lang`, whose filter also decides what counts as the primary (under `lang=de` a German edition is the primary of its name). A reading-order variant of a translation brings the translation and the original it translates. The page stays exactly `limit` long, so a boost costs the last hit rather than widening the response, and a query that resolves none of them returns the plain relevance page.\n\n`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.",
        "parameters": [
          { "$ref": "#/components/parameters/SearchQuery" },
          { "$ref": "#/components/parameters/SearchLimit" },
          { "$ref": "#/components/parameters/Language" },
          { "$ref": "#/components/parameters/Source" }
        ],
        "responses": {
          "200": {
            "description": "One ranked page of mixed results.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["results"],
                  "properties": {
                    "results": {
                      "type": "array",
                      "description": "Hits in rank order, best first. Never null; empty when nothing matched.",
                      "items": { "$ref": "#/components/schemas/SearchResult" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`q` was missing, empty or whitespace only, a `lang` item is not a language tag, or `source` names no source type."
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/works/search": {
      "get": {
        "tags": ["Search"],
        "operationId": "searchWorks",
        "summary": "Search works only",
        "description": "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.\n\nBoth 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.",
        "parameters": [
          { "$ref": "#/components/parameters/SearchQuery" },
          { "$ref": "#/components/parameters/SearchLimit" },
          { "$ref": "#/components/parameters/Language" },
          { "$ref": "#/components/parameters/Source" }
        ],
        "responses": {
          "200": {
            "description": "One ranked page of works.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["results"],
                  "properties": {
                    "results": {
                      "type": "array",
                      "description": "Hits in rank order, best first. Never null; empty when nothing matched.",
                      "items": { "$ref": "#/components/schemas/WorkResult" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`q` was missing, empty or whitespace only, a `lang` item is not a language tag, or `source` names no source type."
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/people/search": {
      "get": {
        "tags": ["Search"],
        "operationId": "searchPeople",
        "summary": "Search people only",
        "description": "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.",
        "parameters": [
          { "$ref": "#/components/parameters/SearchQuery" },
          { "$ref": "#/components/parameters/SearchLimit" },
          {
            "$ref": "#/components/parameters/Language",
            "description": "Accepted and IGNORED: a person has no language, so there is nothing to narrow by. It is still validated, so a value that is not a language list is a 400 here as on the other searches - one request shape serves all four."
          }
        ],
        "responses": {
          "200": {
            "description": "One ranked page of people.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["results"],
                  "properties": {
                    "results": {
                      "type": "array",
                      "description": "Hits in rank order, best first. Never null; empty when nothing matched.",
                      "items": { "$ref": "#/components/schemas/PersonResult" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`q` was missing, empty or whitespace only, or a `lang` item is not a language tag."
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/series/search": {
      "get": {
        "tags": ["Search"],
        "operationId": "searchSeries",
        "summary": "Search series only",
        "description": "The combined search restricted to series. Results are `SeriesResult` objects, each carrying the series' member count, its derived language and what it is - the series a translation translates, the primary a reading-order variant is a view of. Neither work boost applies - what they resolve is always a work.\n\nA query that IS a series' name - compared whole, ignoring case, spacing and punctuation - ranks the page's series of that name first: the primary series (one that is neither a translation nor a reading-order variant) leads, then same-named translations, then same-named variants, each group in id order, and partial matches follow in relevance order. A translation or variant is ranked behind only a same-named series it actually translates or is a view of; one linked to some other series ranks as a primary. So \"harry potter\" lists the English Harry Potter ahead of its German and Spanish editions, which share its name. Any other series on the page sharing one name are ordered the same way within the places they already hold, so a half-typed \"harry pot\" also lists the English series first among them while every other result keeps its place. A `limit` smaller than the number of same-named series may hold translations and variants without their primary; when they name it (`translation_of`, `ordering_of`) under the same name, the primary is pulled onto the page and ranked ahead of them - also when an unrelated series of that name is on the page - and the page is cut back to `limit` (a full page loses its last result), so `limit=1` on \"harry potter\", or on a half-typed \"harry pot\", returns the English series. A reading-order variant of a translation brings the translation too, ranked between the original and the variant. The ranking obeys `lang`: under `lang=de` the English series is not on the page, is not pulled, and the German edition leads - it is the primary of its name there, so a German reading-order variant of it pulls the German edition.\n\n`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.",
        "parameters": [
          { "$ref": "#/components/parameters/SearchQuery" },
          { "$ref": "#/components/parameters/SearchLimit" },
          { "$ref": "#/components/parameters/Language" }
        ],
        "responses": {
          "200": {
            "description": "One ranked page of series.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["results"],
                  "properties": {
                    "results": {
                      "type": "array",
                      "description": "Hits in rank order, best first. Never null; empty when nothing matched.",
                      "items": { "$ref": "#/components/schemas/SeriesResult" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`q` was missing, empty or whitespace only, or a `lang` item is not a language tag."
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/works/latest": {
      "get": {
        "tags": ["Works"],
        "operationId": "latestWorks",
        "summary": "Recently added works",
        "description": "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.\n\n`lang` lists only works in the named languages, and the series cap is taken over those.\n\n`source` lists only works with a recording from that source and orders them by their newest such recording rather than by the work (the work's own date when none of those recordings has one), so a new LibriVox reading of a long-catalogued classic is listed as new.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many works to return. Capped at 50; a non-numeric or non-positive value falls back to the default (12) rather than being clamped to 1.",
            "schema": { "type": "integer", "default": 12, "minimum": 1, "maximum": 50 }
          },
          { "$ref": "#/components/parameters/Language" },
          { "$ref": "#/components/parameters/Source" }
        ],
        "responses": {
          "200": {
            "description": "The newest work cards.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["works"],
                  "properties": {
                    "works": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/WorkCard" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "A `lang` item is not a language tag, or `source` names no source type."
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/works/match": {
      "get": {
        "tags": ["Search"],
        "operationId": "matchWorks",
        "summary": "Match a file against the catalogue",
        "description": "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.\n\nScoring: 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 and ranks first among the results at its score, so a `limit` never leaves it out. A named title that clearly disagrees outranks a numbering match, a title guess that is only a `series` guess's name never lets another volume outrank a stated one (except a work titled that name, stopwords aside, unless a title guess ties the volume being read to that name), named authors none of whom wrote a work scale its score down, and so does a work placed in the named series at another position than the stated one (unless one of its memberships is a range covering it, an omnibus), in the typed text's reading too unless the text names that work, its title or its volume. With `narrator` stated, narrator agreement is a further fact weighted 10, judged only when a recording of the work credits narrators. A known `language` other than the stated one, and a closest recording more than 25% off `runtime`, scale the score down too (neither touches an identifier hit).\n\nBounds: 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, `expand` included; past that the answer is a 503 with `Retry-After`, except that an `expand` the time does not cover is left out rather than failing the match. Nothing is cached server-side, and a successful response carries the searches' short `Cache-Control: public, max-age=60`.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free text as a person typed it, in any order of title, author and series words.",
            "schema": { "type": "string" }
          },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "description": "A title guess: a tag, a folder or file name. Repeat for several; the first 4 are read. Send it as named: numbering and edition fluff are taken off here (`02 - `, `SW06 - `, `Sharpe - 08 - `, `(Unabridged)`, `: Series, Book 5`, the `series` name), and the number the numbering carried is the position when `position` is not given. A title that is a `series` guess's name and then a volume number (`He Who Fights with Monsters 4: A LitRPG Adventure`, `The Expanse, Book 3`) states that volume, ahead of the number a numbering prefix in the same guess carried.",
            "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 4 }
          },
          {
            "name": "author",
            "in": "query",
            "required": false,
            "description": "An author guess. Repeat for several; the first 4 are read. A credit naming several people (`A & B`, `A, B`, `A; B`) is read as each of them, and `Cornwell, Bernard` as Bernard Cornwell. Matching is by surname, then first name or initial.",
            "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 4 }
          },
          {
            "name": "series",
            "in": "query",
            "required": false,
            "description": "A series name guess: the folder a book sits in, a series tag. Repeat for both; the first 2 are read, each is judged and the better agreement counts, so a wrong guess (an author's folder in a `Fiction/<author>/<book>` layout) costs nothing beside a right one. Numbering is taken off (`03 - Tawny Man` is `Tawny Man`).",
            "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 2 }
          },
          {
            "name": "position",
            "in": "query",
            "required": false,
            "description": "The book's position in `series` (`8`, `08`, `7.5`): one value, applied to whichever `series` guess agrees best. Compared numerically, so `08` is `8`. A value that is not a position is ignored. When absent, the number a title guess's numbering carries is used.",
            "schema": { "type": "string" }
          },
          {
            "name": "runtime",
            "in": "query",
            "required": false,
            "description": "The book's length in seconds. A recording within 3% agrees fully, within 10% partly. A work whose closest recording is more than 25% off (allowing the minute a stored runtime is rounded to) is another edition, and its score is scaled down. A non-numeric or non-positive value, or one above 1,000,000, is ignored.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 }
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "The book's language: a BCP-47 tag (`en`, `en-US`; only the primary subtag is compared), an ISO 639-2 code (`eng`, `ger`) or a language's name (`English`, `Deutsch`). A work in another KNOWN language (a translation stored as its own work) has its score scaled down. A value that names no language this API reads, or a work whose language is unknown, is not judged. It finds no candidates on its own.",
            "schema": { "type": "string" }
          },
          {
            "name": "narrator",
            "in": "query",
            "required": false,
            "description": "A narrator guess. Repeat for several; the first 4 are read, each split and matched like `author`. When a recording of a work credits narrators, the best-agreeing recording's agreement counts as a fact weighted 10, and that recording is the `recording_id` (the closest runtime choosing between agreeing recordings) unless it is more than 25% off `runtime`, another edition, when the runtime's pick stands. A work whose recordings credit no narrator is not judged on it. It finds no candidates on its own.",
            "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 4 }
          },
          {
            "name": "asin",
            "in": "query",
            "required": false,
            "description": "An Audible ASIN, looked up exactly as on `/api/v1/lookup`; a hit scores 100. A value longer than 20 characters is ignored.",
            "schema": { "type": "string", "maxLength": 20 }
          },
          {
            "name": "isbn",
            "in": "query",
            "required": false,
            "description": "An ISBN, hyphens and spaces allowed, looked up exactly as on `/api/v1/lookup`; a hit scores 100. A value longer than 20 characters once the hyphens and spaces are taken out is ignored.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many results to return. Capped at 20; a non-numeric or non-positive value falls back to the default (10).",
            "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 20 }
          },
          {
            "name": "expand",
            "in": "query",
            "required": false,
            "description": "What to inline, as a comma-separated list or by repeating the parameter. `work` puts on the best result (the first; an identifier hit ranks first) its `work`, exactly as `GET /api/v1/works/{id}` serves it, and its `series_facts`, so a client matching a whole library does not fetch either on its own. Only that one result carries them, and no series' member list is ever included. A value this server does not read is ignored, and so is the whole parameter on an older server. Treat the inlined members as a saving, never as a promise: they are read inside the match's own budget and left out when they do not fit in it, with the rest of the answer unchanged. `lean` beside `work` inlines the work without its characters, recaps, `recap_summary` and `position_scale` (the community sidecars, most of a long work's bytes; the `community_description` stays); send both, so an older server that does not read `lean` still inlines the whole work. `lean` alone inlines nothing.",
            "schema": { "type": "array", "items": { "type": "string", "enum": ["work", "lean"] } },
            "style": "form",
            "explode": false
          },
          {
            "name": "expand_min",
            "in": "query",
            "required": false,
            "description": "With `expand`: the score (1-100) under which the best result is not expanded (an identifier hit scores 100), for a client that drops a weak best unread. A value outside 1-100 is ignored, and so is the parameter on an older server, which expands whatever the score.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
          }
        ],
        "responses": {
          "200": {
            "description": "The candidates, best first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["results"],
                  "properties": {
                    "results": {
                      "type": "array",
                      "description": "Candidates in rank order, best first. Never null; empty when nothing scored at all.",
                      "items": { "$ref": "#/components/schemas/MatchResult" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "None of `q`, `title`, `author`, `series`, `asin` or `isbn` carried a value."
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": {
            "description": "Either no artifact has loaded yet (see the other routes' 503), or the match could not start or finish within its 2-second budget. Both are temporary; `Retry-After` says when to try again.",
            "headers": {
              "Retry-After": { "$ref": "#/components/headers/RetryAfter" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/v1/watch/feed.atom": {
      "get": {
        "tags": ["Watch feeds"],
        "operationId": "watchFeedAtom",
        "summary": "Watched-series Atom feed",
        "description": "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.",
        "parameters": [
          { "$ref": "#/components/parameters/WatchSeries" },
          { "$ref": "#/components/parameters/WatchWindow" }
        ],
        "responses": {
          "200": {
            "description": "The Atom 1.0 feed.",
            "content": {
              "application/atom+xml": {
                "schema": { "type": "string", "description": "An Atom 1.0 XML document." }
              }
            }
          },
          "304": { "description": "The supplied `If-None-Match` validator still names this feed." },
          "400": {
            "description": "`s` is missing or invalid, contains more than 200 series, or `window` is outside 1-365.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/watch/feed.json": {
      "get": {
        "tags": ["Watch feeds"],
        "operationId": "watchFeedJSON",
        "summary": "Watched-series JSON Feed",
        "description": "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.",
        "parameters": [
          { "$ref": "#/components/parameters/WatchSeries" },
          { "$ref": "#/components/parameters/WatchWindow" }
        ],
        "responses": {
          "200": {
            "description": "The JSON Feed 1.1 document.",
            "content": {
              "application/feed+json": {
                "schema": { "$ref": "#/components/schemas/JSONFeed" }
              }
            }
          },
          "304": { "description": "The supplied `If-None-Match` validator still names this feed." },
          "400": {
            "description": "`s` is missing or invalid, contains more than 200 series, or `window` is outside 1-365.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/watch/releases.ics": {
      "get": {
        "tags": ["Watch feeds"],
        "operationId": "watchReleasesICS",
        "summary": "Watched-series release calendar",
        "description": "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 `UID`s 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.",
        "parameters": [
          { "$ref": "#/components/parameters/WatchSeries" },
          { "$ref": "#/components/parameters/WatchWindow" }
        ],
        "responses": {
          "200": {
            "description": "The iCalendar document.",
            "content": {
              "text/calendar": {
                "schema": { "type": "string", "description": "An RFC 5545 `VCALENDAR` document holding one all-day `VEVENT` per dated work." }
              }
            }
          },
          "304": { "description": "The supplied `If-None-Match` validator still names this calendar." },
          "400": {
            "description": "`s` is missing or invalid, contains more than 200 series, or `window` is outside 1-365.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
            }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/works/{id}": {
      "get": {
        "tags": ["Works"],
        "operationId": "work",
        "summary": "One work in full",
        "description": "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.\n\n`characters`, `recaps`, `recap_summary`, `community_description`, `position_scale` and `genres` depend on the loaded artifact's internal schema version and are omitted - never faked - when the artifact predates them.\n\nA slug a merge has retired answers 301 at the work that replaced it, so a stored id keeps resolving.",
        "parameters": [{ "$ref": "#/components/parameters/WorkID" }],
        "responses": {
          "200": {
            "description": "The work document.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WorkDetail" }
              }
            }
          },
          "301": { "$ref": "#/components/responses/Retired" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/works/{id}/recordings/{rid}/chapters": {
      "get": {
        "tags": ["Works"],
        "operationId": "chapters",
        "summary": "One recording's chapter list",
        "description": "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.",
        "parameters": [
          { "$ref": "#/components/parameters/WorkID" },
          { "$ref": "#/components/parameters/RecordingID" }
        ],
        "responses": {
          "200": {
            "description": "The recording's chapters (empty when it has none, or does not exist).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["chapters"],
                  "properties": {
                    "chapters": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Chapter" }
                    }
                  }
                }
              }
            }
          },
          "301": { "$ref": "#/components/responses/Retired" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/people/{id}": {
      "get": {
        "tags": ["People & Series"],
        "operationId": "person",
        "summary": "One person and a page of their credits",
        "description": "A person with one page of each credit list - works authored and recordings narrated. Both lists take the same window.\n\nThe 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.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The person's slug, e.g. `ray-porter`.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Credits per list. Capped at 500; a non-numeric or non-positive value falls back to the default (100) rather than being clamped to 1.",
            "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }
          },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": {
            "description": "The person and one page of each credit list.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PersonDetail" }
              }
            }
          },
          "301": { "$ref": "#/components/responses/Retired" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/series/{id}": {
      "get": {
        "tags": ["People & Series"],
        "operationId": "series",
        "summary": "One series and its member works",
        "description": "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.\n\nUnlike 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.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The series' slug, e.g. `the-stormlight-archive`.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Member works to return. ABSENT means the whole series (there is no default window); a supplied value is capped at 500. A non-numeric or non-positive value falls back to that same default - the WHOLE series - rather than being clamped to 1.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 500 }
          },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": {
            "description": "The series and its member works.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SeriesDetail" }
              }
            }
          },
          "301": { "$ref": "#/components/responses/Retired" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/series/{id}/listening-guide": {
      "get": {
        "tags": [
          "People & Series"
        ],
        "operationId": "seriesListeningGuide",
        "summary": "One page of a series listening guide",
        "description": "Works in numeric series order with at most five recording alternatives per work, selected deterministically by recording id. Decimal and range positions remain strings. `recordings_total` includes alternatives beyond the cap; zero means no recording catalogued. Only the visible page is composed. Runtimes describe separate alternatives and must not be summed without an explicit choice per work. Retailer availability is not inferred.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The record slug. Retired slugs redirect at this same route.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size, default 50 and at most 100. Invalid or non-positive values use the default.",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "$ref": "#/components/parameters/Offset"
          }
        ],
        "responses": {
          "200": {
            "description": "One page of a series listening guide.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SeriesListeningGuide"
                }
              }
            }
          },
          "301": {
            "$ref": "#/components/responses/Retired"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/NoData"
          }
        }
      }
    },
    "/api/v1/people/{id}/recordings": {
      "get": {
        "tags": [
          "People & Series"
        ],
        "operationId": "personRecordings",
        "summary": "One page of narration recording credits",
        "description": "Recording-level narration credits, retaining separate recordings of one work. `series` memberships are provided for grouping the visible page; filtering is optional. Authorship and translation credits remain on the existing person detail route.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The record slug. Retired slugs redirect at this same route.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size, default 50 and at most 100. Invalid or non-positive values use the default.",
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "$ref": "#/components/parameters/Offset"
          },
          {
            "name": "series",
            "in": "query",
            "description": "An optional series slug. Invalid slugs are rejected.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "description": "Optional primary language subtag or comma-separated primary subtags. Invalid tags are rejected.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of narration recording credits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PersonRecordingsPage"
                }
              }
            }
          },
          "301": {
            "$ref": "#/components/responses/Retired"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          },
          "503": {
            "$ref": "#/components/responses/NoData"
          }
        }
      }
    },
    "/api/v1/lookup": {
      "get": {
        "tags": ["Lookup"],
        "operationId": "lookup",
        "summary": "Resolve an ASIN, ISBN or LibriVox id to a recording",
        "description": "Exact identifier resolution: given an Audible ASIN, an ISBN or a LibriVox project id, return the work card and the id of the recording that identifier names. Supply one of the three; `asin` wins over `isbn`, and `librivox_id` is read only when neither of the others is given.\n\nAn 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).",
        "parameters": [
          {
            "name": "asin",
            "in": "query",
            "required": false,
            "description": "An Audible ASIN, e.g. `B08G9PRS1K`. Takes precedence over `isbn`.",
            "schema": { "type": "string" }
          },
          {
            "name": "isbn",
            "in": "query",
            "required": false,
            "description": "A bare 10- or 13-digit ISBN, e.g. `9781427209269`.",
            "schema": { "type": "string" }
          },
          {
            "name": "librivox_id",
            "in": "query",
            "required": false,
            "description": "A LibriVox project id, e.g. `52`: the number in the project's LibriVox API answer, not its catalogue page slug. Read only when `asin` and `isbn` are absent. Not a positive integer is a 400; an artifact older than version 8 holds no LibriVox recording, so there it is a 404.",
            "schema": { "type": "integer", "minimum": 1, "examples": [52] }
          }
        ],
        "responses": {
          "200": {
            "description": "The work and recording the identifier names.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LookupResult" }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "None of `asin`, `isbn` and `librivox_id` was supplied, or `librivox_id` is not a positive integer."
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/librivox/audiobooks": {
      "get": {
        "tags": ["LibriVox"],
        "operationId": "librivoxAudiobooks",
        "summary": "LibriVox-shaped audiobooks feed",
        "description": "LibriVox's audiobooks feed (`librivox.org/api/feed/audiobooks`) answered from the mirror, with LibriVox's parameters and JSON shape, so an app that reads LibriVox can switch by changing its base URL.\n\nThe answer differs from LibriVox's in the facts the mirror does not keep: `description`, `url_project` and `url_other` are empty strings, `coverart_pdf` and `coverart_thumbnail` are null, a section's `id` is empty, its `file_name` null and its `language` the project's language, a genre's `id` is empty (and a genre LibriVox lists twice is listed once), an author's `first_name` and `last_name` are the stored name split at its last word, and `dob`/`dod` are years or empty. Everything else is LibriVox's value as the mirror stored it: the project's own `title` (its \"(version N)\" marker and spelling kept), each section's own `section_number` (LibriVox numbers some projects from 0) and `readers`, the project's own `translators` and its LibriVox `genres` names, and ids, the language name, `copyright_year`, URLs, runtimes, section titles, listen URLs and playtimes. A translator the mirror credits by name without a LibriVox id carries no `id` or years.\n\nOn an artifact older than version 9 the feed answers as it did before: the catalogue work's title without \"(version N)\", 1-based positions as section numbers, the work's translator credits, this project's vocabulary as `genres` (and as the `genre` filter), and a section reader only for a recording with one narrator.\n\nAt most 500 projects a request. A reader that wants the whole catalogue should download the `meta.sqlite.gz` release asset instead.",
        "parameters": [
          { "name": "id", "in": "query", "required": false, "description": "One LibriVox project id. Not a positive integer is a 400.", "schema": { "type": "integer", "minimum": 1 } },
          { "name": "since", "in": "query", "required": false, "description": "A UNIX time: only the projects that reached the mirror on or after that day (compared at day granularity, from midnight UTC, as LibriVox compares its catalogue date). The date is when the mirror imported the recording, not when LibriVox catalogued it. Not a non-negative integer is a 400.", "schema": { "type": "integer", "minimum": 0 } },
          { "name": "title", "in": "query", "required": false, "description": "The project's own title (LibriVox's, its `(version N)` marker kept), matched exactly and case-insensitively; a leading `^` makes it a prefix match. On an artifact older than version 9, the work's title.", "schema": { "type": "string" } },
          { "name": "author", "in": "query", "required": false, "description": "An author's last name (the last word of the stored name), matched exactly and case-insensitively, or with a leading `^` as a prefix. A translator never matches.", "schema": { "type": "string" } },
          { "name": "genre", "in": "query", "required": false, "description": "One of the project's own LibriVox genre names (for example `Science Fiction`), matched exactly and case-insensitively, or with a leading `^` as a prefix - never widened through this project's vocabulary. On an artifact older than version 9, a LibriVox genre name the importer maps or a vocabulary value (`science-fiction`).", "schema": { "type": "string" } },
          { "name": "extended", "in": "query", "required": false, "description": "`1` adds `url_iarchive`, `sections`, `genres` and `translators`. Empty or `0` is off.", "schema": { "type": "string", "examples": ["1"] } },
          { "name": "coverart", "in": "query", "required": false, "description": "`1` adds `coverart_jpg`, `coverart_pdf` and `coverart_thumbnail`. Empty or `0` is off.", "schema": { "type": "string", "examples": ["1"] } },
          { "name": "fields", "in": "query", "required": false, "description": "Keep only these top-level fields: `{id,title}`, a comma list, or repeated as `fields[]`.", "schema": { "type": "string", "examples": ["{id,title,authors}"] } },
          { "name": "limit", "in": "query", "required": false, "description": "How many projects to return: default 50, at most 500. Over 500 is a 400, as LibriVox answers; empty or `0` is the default.", "schema": { "type": "integer", "default": 50, "minimum": 0, "maximum": 500 } },
          { "name": "offset", "in": "query", "required": false, "description": "How many matching projects to skip. Not a non-negative integer is a 400.", "schema": { "type": "integer", "default": 0, "minimum": 0 } },
          { "name": "sort_order", "in": "query", "required": false, "description": "`desc` orders by project id descending; anything else ascending.", "schema": { "type": "string", "examples": ["desc"] } },
          { "name": "format", "in": "query", "required": false, "description": "Only `json` (the default) is served. The XML, JSONP and PHP forms LibriVox offers are a 400.", "schema": { "type": "string", "enum": ["json"] } }
        ],
        "responses": {
          "200": {
            "description": "One page of projects, in LibriVox's shape.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["books"],
                  "properties": {
                    "books": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/LibrivoxAudiobook" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "A parameter is malformed, `limit` is over 500, or `format` is not `json`."
          },
          "404": {
            "description": "No project matched, or the loaded artifact is older than version 8. The body is LibriVox's own: `{\"error\": \"Audiobooks could not be found\"}`.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/librivox/audiobooks/": {
      "get": {
        "tags": ["LibriVox"],
        "operationId": "librivoxAudiobooksSlash",
        "summary": "LibriVox-shaped audiobooks feed (trailing-slash spelling)",
        "description": "The same feed at the trailing-slash path LibriVox documents (`/api/feed/audiobooks/?id=52`), so a client built against that spelling needs only its host changed.",
        "parameters": [
          { "name": "id", "in": "query", "required": false, "description": "One LibriVox project id. Not a positive integer is a 400.", "schema": { "type": "integer", "minimum": 1 } },
          { "name": "since", "in": "query", "required": false, "description": "A UNIX time: only the projects that reached the mirror on or after that day (compared at day granularity, from midnight UTC, as LibriVox compares its catalogue date). The date is when the mirror imported the recording, not when LibriVox catalogued it. Not a non-negative integer is a 400.", "schema": { "type": "integer", "minimum": 0 } },
          { "name": "title", "in": "query", "required": false, "description": "The project's own title (LibriVox's, its `(version N)` marker kept), matched exactly and case-insensitively; a leading `^` makes it a prefix match. On an artifact older than version 9, the work's title.", "schema": { "type": "string" } },
          { "name": "author", "in": "query", "required": false, "description": "An author's last name (the last word of the stored name), matched exactly and case-insensitively, or with a leading `^` as a prefix. A translator never matches.", "schema": { "type": "string" } },
          { "name": "genre", "in": "query", "required": false, "description": "One of the project's own LibriVox genre names (for example `Science Fiction`), matched exactly and case-insensitively, or with a leading `^` as a prefix - never widened through this project's vocabulary. On an artifact older than version 9, a LibriVox genre name the importer maps or a vocabulary value (`science-fiction`).", "schema": { "type": "string" } },
          { "name": "extended", "in": "query", "required": false, "description": "`1` adds `url_iarchive`, `sections`, `genres` and `translators`. Empty or `0` is off.", "schema": { "type": "string", "examples": ["1"] } },
          { "name": "coverart", "in": "query", "required": false, "description": "`1` adds `coverart_jpg`, `coverart_pdf` and `coverart_thumbnail`. Empty or `0` is off.", "schema": { "type": "string", "examples": ["1"] } },
          { "name": "fields", "in": "query", "required": false, "description": "Keep only these top-level fields: `{id,title}`, a comma list, or repeated as `fields[]`.", "schema": { "type": "string", "examples": ["{id,title,authors}"] } },
          { "name": "limit", "in": "query", "required": false, "description": "How many projects to return: default 50, at most 500. Over 500 is a 400, as LibriVox answers; empty or `0` is the default.", "schema": { "type": "integer", "default": 50, "minimum": 0, "maximum": 500 } },
          { "name": "offset", "in": "query", "required": false, "description": "How many matching projects to skip. Not a non-negative integer is a 400.", "schema": { "type": "integer", "default": 0, "minimum": 0 } },
          { "name": "sort_order", "in": "query", "required": false, "description": "`desc` orders by project id descending; anything else ascending.", "schema": { "type": "string", "examples": ["desc"] } },
          { "name": "format", "in": "query", "required": false, "description": "Only `json` (the default) is served. The XML, JSONP and PHP forms LibriVox offers are a 400.", "schema": { "type": "string", "enum": ["json"] } }
        ],
        "responses": {
          "200": {
            "description": "One page of projects, in LibriVox's shape.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["books"],
                  "properties": {
                    "books": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/LibrivoxAudiobook" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "A parameter is malformed, `limit` is over 500, or `format` is not `json`."
          },
          "404": {
            "description": "No project matched, or the loaded artifact is older than version 8. The body is LibriVox's own: `{\"error\": \"Audiobooks could not be found\"}`.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/coverage": {
      "get": {
        "tags": ["Coverage"],
        "operationId": "coverage",
        "summary": "Expressive-layer totals",
        "description": "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\".",
        "responses": {
          "200": {
            "description": "The top-line coverage totals.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CoverageResult" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/coverage/works": {
      "get": {
        "tags": ["Coverage"],
        "operationId": "coverageWorks",
        "summary": "Works by expressive-layer status",
        "description": "One filtered, searchable, paginated page of works for the coverage browser. Each row lists which parts of the community layer it still lacks.\n\n`available` is false (with an empty page) when the requested filter's dimension cannot be evaluated against the loaded artifact.",
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "description": "Which works to list. An empty value means `missing`.",
            "schema": {
              "type": "string",
              "default": "missing",
              "enum": ["missing", "has_characters", "has_recaps", "has_recap_summary", "has_description"]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Narrow by full-text query over the work's title and subtitle and the names of its authors, narrators and series. Whole word or word prefix, the same matching as /api/v1/search.",
            "schema": { "type": "string" }
          },
          { "$ref": "#/components/parameters/Language" },
          { "$ref": "#/components/parameters/PageLimit" },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": {
            "description": "One page of works for the filter.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CoverageWorksResult" }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "Unrecognized `filter` value, or a `lang` item that is not a language tag."
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/api/v1/coverage/series-gaps": {
      "get": {
        "tags": ["Coverage"],
        "operationId": "coverageSeriesGaps",
        "summary": "Series with missing volumes",
        "description": "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.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive substring of the series name.",
            "schema": { "type": "string" }
          },
          { "$ref": "#/components/parameters/PageLimit" },
          { "$ref": "#/components/parameters/Offset" }
        ],
        "responses": {
          "200": {
            "description": "One page of series with gaps.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SeriesGapsResult" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/abs/search": {
      "get": {
        "tags": ["Audiobookshelf provider"],
        "operationId": "absSearch",
        "summary": "Audiobookshelf custom metadata provider",
        "description": "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.\n\nThe 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.\n\nAn `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.\n\nAttribution: `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.\n\nA library in one language can rank its own language first through `/abs/{lang}/search` instead.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "The title Audiobookshelf is matching. Required. Matched like the `q` of /api/v1/search, so a title read off a file name without its apostrophes (\"Enders Game\") still finds the work, and a title written with one finds a work stored without it.",
            "schema": { "type": "string" }
          },
          {
            "name": "author",
            "in": "query",
            "required": false,
            "description": "The author string Audiobookshelf holds. Loosely matched, and used only to rank.",
            "schema": { "type": "string" }
          },
          {
            "name": "isbn",
            "in": "query",
            "required": false,
            "description": "An ISBN, hyphenated or bare. When it resolves exactly, that recording's work is returned and the title search is skipped.",
            "schema": { "type": "string" }
          },
          {
            "name": "mediaType",
            "in": "query",
            "required": false,
            "description": "Always `book` when Audiobookshelf sends it. Accepted and ignored.",
            "schema": { "type": "string", "enum": ["book"] }
          }
        ],
        "responses": {
          "200": {
            "description": "The matches, best first. Always an array, possibly empty.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ABSSearchResult" }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`query` was missing or empty."
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/abs/{lang}/search": {
      "get": {
        "tags": ["Audiobookshelf provider"],
        "operationId": "absSearchLanguage",
        "summary": "Audiobookshelf provider, ranked toward a language",
        "description": "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.\n\nThe 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.",
        "parameters": [
          {
            "name": "lang",
            "in": "path",
            "required": true,
            "description": "One language code, or several separated by commas (`de`, `de,en`). Matched by primary subtag, so `de` also ranks works tagged `de-at` first. A segment that is not a language list is a 404.",
            "schema": { "type": "string" }
          },
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "The title Audiobookshelf is matching. Required. Matched exactly as on `/abs/search`.",
            "schema": { "type": "string" }
          },
          {
            "name": "author",
            "in": "query",
            "required": false,
            "description": "The author string Audiobookshelf holds. Loosely matched, used only to rank, and ranked ahead of the language.",
            "schema": { "type": "string" }
          },
          {
            "name": "isbn",
            "in": "query",
            "required": false,
            "description": "An ISBN, hyphenated or bare. When it resolves exactly, that recording's work is returned and neither ranking applies.",
            "schema": { "type": "string" }
          },
          {
            "name": "mediaType",
            "in": "query",
            "required": false,
            "description": "Always `book` when Audiobookshelf sends it. Accepted and ignored.",
            "schema": { "type": "string", "enum": ["book"] }
          }
        ],
        "responses": {
          "200": {
            "description": "The matches, best first. Always an array, possibly empty.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ABSSearchResult" }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest",
            "description": "`query` was missing or empty."
          },
          "404": {
            "$ref": "#/components/responses/NotFound",
            "description": "The path segment is not a language list."
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/NoData" }
        }
      }
    },
    "/hooks/github/release": {
      "post": {
        "tags": ["Server"],
        "operationId": "githubReleaseWebhook",
        "summary": "Release notification (production only)",
        "description": "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.\n\nThe 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.\n\nError bodies on this route are plain text, not the JSON error envelope the API uses.",
        "parameters": [
          {
            "name": "X-Hub-Signature-256",
            "in": "header",
            "required": true,
            "description": "`sha256=<hex>` HMAC-SHA256 of the raw request body, keyed with the deployment's webhook secret.",
            "schema": { "type": "string" }
          },
          {
            "name": "X-GitHub-Event",
            "in": "header",
            "required": false,
            "description": "GitHub's event name. Anything other than `release` is accepted and ignored.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ReleaseWebhook" }
            }
          }
        },
        "responses": {
          "202": { "description": "Accepted. A refresh runs in the background if the payload named a published release of this repository." },
          "400": { "description": "Unreadable body, or a signed payload that is not valid JSON. Plain text." },
          "401": { "description": "Missing or invalid `X-Hub-Signature-256`. Plain text." },
          "413": { "description": "Body over 1 MiB. Plain text." }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RetryAfter": {
        "description": "Whole seconds to wait before retrying. It reports the wait the server's refresh loop is actually on, which grows as attempts fail.",
        "schema": { "type": "integer", "minimum": 1 }
      },
      "Location": {
        "description": "The same route under the slug that replaced the retired one, carrying the request's own query string unchanged. Each path segment is escaped exactly once, so it is usable as a request target as it stands.",
        "schema": { "type": "string", "examples": ["/api/v1/works/project-hail-mary"] }
      }
    },
    "parameters": {
      "SearchQuery": {
        "name": "q",
        "in": "query",
        "required": true,
        "description": "The search query. Matching is by whole word or word prefix, with punctuation as a word boundary - though an initialism (a run of single-letter fragments, as in \"Q&A\") is matched as one adjacent phrase, and a possessive matches in either spelling (\"enders\" finds \"Ender's\", \"finnegan's\" finds \"Finnegans\"); an empty or whitespace-only value is a 400, while a value holding no word at all (only punctuation) is an ordinary empty result page.",
        "schema": { "type": "string", "minLength": 1 }
      },
      "SearchLimit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "How many results to return. Capped at 50; a non-numeric or non-positive value falls back to the default (20) rather than being clamped to 1.",
        "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 }
      },
      "Language": {
        "name": "lang",
        "in": "query",
        "required": false,
        "description": "Only works in these languages: one code or several separated by commas (`de`, `de,en`); a repeated parameter reads as one list. Matched by primary subtag, so `de` also matches a work tagged `de-at`, and a regional item (`pt-br`) matches as its primary subtag. Absent or empty means every language. At most 8 codes; an item that is not a language tag is a 400, while a code the catalogue holds no works in simply matches nothing. A record with no language - a person, or a series whose members tie - is never excluded. Against an artifact older than the languages layer the value is validated and then ignored.",
        "schema": { "type": "string", "examples": ["de", "de,en"] }
      },
      "Source": {
        "name": "source",
        "in": "query",
        "required": false,
        "description": "Only works with at least one recording from this source type, for example `librivox` for the free public-domain LibriVox recordings. The filter runs inside the query, the boosts obey it, and on the combined search it scopes the page to works (a person or a series has no recording). A value that is not a source type of the schema is a 400. Against an artifact older than version 8 a filtered list is empty.",
        "schema": { "type": "string", "examples": ["librivox"] }
      },
      "PageLimit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Rows per page. Capped at 100; a non-numeric or non-positive value falls back to the default (25) rather than being clamped to 1.",
        "schema": { "type": "integer", "default": 25, "minimum": 1, "maximum": 100 }
      },
      "Offset": {
        "name": "offset",
        "in": "query",
        "required": false,
        "description": "Rows to skip. A negative or non-numeric value is treated as 0.",
        "schema": { "type": "integer", "default": 0, "minimum": 0 }
      },
      "WatchSeries": {
        "name": "s",
        "in": "query",
        "required": true,
        "description": "One to 200 series slugs as comma-separated values, or the compact form `z:<base64url(deflate(csv))>`. The compact form uses raw DEFLATE with no zlib header and unpadded base64url.",
        "schema": { "type": "string", "minLength": 1 }
      },
      "WatchWindow": {
        "name": "window",
        "in": "query",
        "required": false,
        "description": "How many days of released or newly catalogued works to include. Future release dates are included regardless of this window.",
        "schema": { "type": "integer", "default": 90, "minimum": 1, "maximum": 365 }
      },
      "WorkID": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The work's slug, e.g. `project-hail-mary`.",
        "schema": { "type": "string" }
      },
      "RecordingID": {
        "name": "rid",
        "in": "path",
        "required": true,
        "description": "The recording's slug, unique within its work, e.g. `ray-porter-2021`.",
        "schema": { "type": "string" }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "`q` was missing, empty or whitespace only.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NotFound": {
        "description": "No such record.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "Retired": {
        "description": "The slug was RETIRED - a data-quality repair merged its record into another one - and `Location` names the same route under the slug that replaced it. Following it is an ordinary GET. The body repeats the new slug, so a client that stored the old one can heal it instead of only learning that it is gone. It is answered only for a slug the database no longer holds, and never chains: one redirect always lands on a live record. Despite the status code it is NOT permanent - reversing a bad merge withdraws it - so it carries `Cache-Control: public, max-age=3600` and must not be cached beyond that. An artifact older than internal schema version 5 carries no redirect table, so a retired slug is a 404 there.",
        "headers": {
          "Location": { "$ref": "#/components/headers/Location" }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Redirect" }
          }
        }
      },
      "ServerError": {
        "description": "A query against the loaded artifact failed. Not expected in normal operation - an artifact is checksum-verified before it is served - so read it as a bug or a damaged snapshot rather than a condition to code around. Retrying is safe: the API is read-only.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "TooManyRequests": {
        "description": "This client (its address) is past the per-client rate limit. Wait the `Retry-After` seconds and retry. The answer carries `Cache-Control: no-store`.",
        "headers": {
          "Retry-After": { "$ref": "#/components/headers/RetryAfter" }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "NoData": {
        "description": "No artifact has loaded yet - a cold boot still fetching the newest release. Temporary by construction; `Retry-After` reports the wait the server's refresh loop is on.",
        "headers": {
          "Retry-After": { "$ref": "#/components/headers/RetryAfter" }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "The error envelope every JSON 4xx and 5xx uses. The message is human-facing; branch on the status code, not on its text.",
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "examples": ["q is required"] }
        }
      },
      "Redirect": {
        "type": "object",
        "description": "The body of a 301: the live slug the retired one now stands for, so a stored id can be rewritten rather than merely reported dead.",
        "required": ["redirect"],
        "properties": {
          "redirect": { "type": "string", "examples": ["project-hail-mary"] }
        }
      },
      "JSONFeedAuthor": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string" }
        }
      },
      "JSONFeedItem": {
        "type": "object",
        "required": ["id", "url", "title", "content_text", "date_published", "date_modified", "tags"],
        "properties": {
          "id": { "type": "string", "description": "A stable tag URI ending in `preorder` or `released`. A preorder becoming released is a new item." },
          "url": { "type": "string", "description": "The public work page." },
          "title": { "type": "string" },
          "content_text": { "type": "string", "description": "One-line release, preorder or unknown-date summary." },
          "date_published": { "type": "string", "format": "date-time" },
          "date_modified": { "type": "string", "format": "date-time" },
          "authors": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/JSONFeedAuthor" }
          },
          "tags": {
            "type": "array",
            "items": { "type": "string", "enum": ["preorder", "released", "date unknown"] }
          }
        }
      },
      "JSONFeed": {
        "type": "object",
        "required": ["version", "title", "description", "feed_url", "items"],
        "properties": {
          "version": { "type": "string", "const": "https://jsonfeed.org/version/1.1" },
          "title": { "type": "string", "const": "AudioSilo Meta: new in your series" },
          "description": { "type": "string", "description": "The resolved series names plus any slugs not found." },
          "feed_url": { "type": "string", "description": "The absolute request URL under the configured public site origin." },
          "items": {
            "type": "array",
            "description": "At most 200 items, newest first.",
            "items": { "$ref": "#/components/schemas/JSONFeedItem" }
          }
        }
      },
      "Health": {
        "type": "object",
        "required": ["status", "built_at", "works"],
        "properties": {
          "status": { "type": "string", "const": "ok" },
          "built_at": {
            "type": "string",
            "description": "When the loaded artifact was compiled (RFC 3339).",
            "examples": ["2026-07-11T00:00:00Z"]
          },
          "works": { "type": "integer", "description": "Works in the loaded artifact." }
        }
      },
      "HealthStarting": {
        "type": "object",
        "required": ["status"],
        "properties": {
          "status": { "type": "string", "const": "starting" }
        }
      },
      "Stats": {
        "type": "object",
        "required": [
          "works",
          "recordings",
          "people",
          "series",
          "total_runtime_min",
          "total_chapters",
          "built_at"
        ],
        "properties": {
          "works": { "type": "integer" },
          "recordings": { "type": "integer" },
          "people": { "type": "integer", "description": "Authors and narrators share one person record, so this counts both." },
          "series": { "type": "integer" },
          "total_runtime_min": { "type": "integer", "description": "Summed recording runtimes, in minutes." },
          "total_chapters": { "type": "integer" },
          "built_at": {
            "type": "string",
            "description": "When the loaded artifact was compiled (RFC 3339).",
            "examples": ["2026-07-11T00:00:00Z"]
          },
          "languages": {
            "type": "array",
            "description": "How many works each language holds, most works first (ties by tag). Omitted when the loaded artifact predates version 7.",
            "items": { "$ref": "#/components/schemas/LanguageCount" }
          }
        }
      },
      "LanguageCount": {
        "type": "object",
        "required": ["language", "works"],
        "properties": {
          "language": { "type": "string", "description": "A BCP 47 language tag, exactly as the works carry it.", "examples": ["en"] },
          "works": { "type": "integer" }
        }
      },
      "PersonRef": {
        "type": "object",
        "description": "A person by reference. Follow `id` to /api/v1/people/{id} for their credits.",
        "required": ["id", "name"],
        "properties": {
          "id": { "type": "string", "examples": ["ray-porter"] },
          "name": { "type": "string", "examples": ["Ray Porter"] }
        }
      },
      "SeriesRef": {
        "type": "object",
        "description": "A work's membership of one series.",
        "required": ["id", "name", "position"],
        "properties": {
          "id": { "type": "string", "examples": ["the-stormlight-archive"] },
          "name": { "type": "string", "examples": ["The Stormlight Archive"] },
          "position": {
            "type": "string",
            "description": "The volume position as a STRING, so \"2\", \"2.5\" and the omnibus range \"1-3.5\" stay distinct values. Never parse it as a number without preserving the original.",
            "examples": ["2.5"]
          },
          "ordering_of": {
            "type": "string",
            "description": "Present only when this series is a VARIANT reading order (a chronological or recommended listing) of another series: the slug of that primary series. Omitted for the series itself, and when the loaded artifact predates version 7.",
            "examples": ["the-stormlight-archive"]
          }
        }
      },
      "WorkCard": {
        "type": "object",
        "description": "The compact work representation every list and lookup returns. The three nullable fields are always PRESENT - null means the work has no series membership, no cover on any recording, or no recorded date. `release_date` is the one OMITTED field: it is absent when no recording of the work states a release date.",
        "required": ["id", "title", "authors", "language", "series", "cover_url", "added_at"],
        "properties": {
          "id": { "type": "string", "examples": ["project-hail-mary"] },
          "title": { "type": "string", "examples": ["Project Hail Mary"] },
          "authors": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PersonRef" }
          },
          "language": {
            "type": "string",
            "description": "BCP 47 language tag. Always present - every work states one - so a list can tell a work from its translations.",
            "examples": ["en"]
          },
          "series": {
            "description": "The work's FIRST series membership, or null. A work in several series shows only one here - any series that is not a variant reading order before every variant one, then by series id - and /api/v1/works/{id} lists them all.",
            "oneOf": [{ "$ref": "#/components/schemas/SeriesRef" }, { "type": "null" }]
          },
          "release_date": {
            "type": "string",
            "description": "The EARLIEST release date across the work's recordings, at whatever precision the source stated: `YYYY`, `YYYY-MM` or `YYYY-MM-DD`. Earliest is the minimum by plain string order over the values that state one; the field is omitted when none do. A date in the future is a catalogued preorder, not an error.",
            "examples": ["2021-05-04"]
          },
          "cover_url": {
            "type": ["string", "null"],
            "description": "The first cover URL across the work's recordings, or null. Covers are always remote URLs - this project stores no image files."
          },
          "added_at": {
            "type": ["string", "null"],
            "description": "When the work entered the database: `YYYY-MM-DD`, or a full RFC 3339 timestamp for records dated by the one-time history backfill. Null when unknown."
          }
        }
      },
      "WorkResult": {
        "description": "A search hit that is a work: every WorkCard field, plus the kind discriminator and the distinct narrators across the work's recordings. It COMPOSES the card rather than restating it, so the two can never end up describing the same bytes differently; the branches are ordered so the rendered shape matches the order the fields arrive in.",
        "allOf": [
          {
            "type": "object",
            "required": ["kind"],
            "properties": {
              "kind": { "type": "string", "const": "work" }
            }
          },
          { "$ref": "#/components/schemas/WorkCard" },
          {
            "type": "object",
            "required": ["narrators"],
            "properties": {
              "narrators": {
                "type": "array",
                "description": "Every distinct narrator across the work's recordings, in credit order.",
                "items": { "$ref": "#/components/schemas/PersonRef" }
              }
            }
          }
        ]
      },
      "MatchResult": {
        "description": "A works/match candidate: every WorkResult field, plus how well the work fits the request and why.",
        "allOf": [
          { "$ref": "#/components/schemas/WorkResult" },
          {
            "type": "object",
            "required": ["score", "reasons"],
            "properties": {
              "score": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100,
                "description": "How well the work's own facts agree with the request: 100 for an identifier hit, otherwise the better of the structured-facts score and the typed-text score."
              },
              "recording_id": {
                "type": "string",
                "description": "The recording the identifier is on (a work's print ISBN names the work and no recording), else (when `narrator` is given and a recording agrees, not more than 25% off `runtime`) the best-agreeing recording, the closest runtime breaking a tie, else the one whose runtime is closest to `runtime`. Omitted when none applies."
              },
              "reasons": { "$ref": "#/components/schemas/MatchReasons" },
              "work": {
                "$ref": "#/components/schemas/WorkDetail",
                "description": "Only with `expand=work`, only on the best result, and only when it could be read within the match's budget: the work exactly as `GET /api/v1/works/{id}` serves it."
              },
              "series_facts": {
                "type": "object",
                "description": "Beside `work` and never without it: what the records of the work's series say about each of them, by series id. It covers the work's memberships in order, each once, up to 16, leaving out a variant reading order (one with `ordering_of`). A series without an entry is one nothing is known about. Omitted when there are no entries.",
                "additionalProperties": { "$ref": "#/components/schemas/MatchSeriesFacts" }
              }
            }
          }
        ]
      },
      "MatchSeriesFacts": {
        "type": "object",
        "description": "The two facts of a series record a client's series rules read, each the value `GET /api/v1/series/{id}` serves.",
        "properties": {
          "language": {
            "type": "string",
            "description": "The series' derived language. Omitted where its members tie or the artifact predates it."
          },
          "translation_of": {
            "type": "array",
            "items": { "type": "string" },
            "description": "The ids of the series it translates. Omitted when it translates none."
          }
        }
      },
      "MatchReasons": {
        "type": "object",
        "description": "Which facts agreed. A field is omitted when the request did not let it be judged.",
        "properties": {
          "title": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "The best similarity between a title guess and the work's title (1 is the same words)."
          },
          "text": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "The similarity of the typed text, read as a title once the work's own author and series words are taken out of it; 1 when it named the work's series and volume (`sharpe 8`)."
          },
          "author": {
            "type": "string",
            "enum": ["full", "surname", "none"],
            "description": "Whether an author guess names one of the work's authors: by surname and first name, by surname only, or not at all."
          },
          "series": {
            "type": "string",
            "enum": ["position", "name", "conflict", "none"],
            "description": "How the work's series fit `series` and `position`: both agree; the series agrees and no position was asked; the series agrees but the position does not, or the title clearly names another volume; no series fits."
          },
          "runtime": {
            "type": "number",
            "minimum": 0,
            "description": "The relative difference between `runtime` and the closest recording's (0.02 is 2%)."
          },
          "identifier": {
            "type": "string",
            "enum": ["asin", "isbn"],
            "description": "Present when the work was found by that identifier."
          },
          "narrator": {
            "type": "string",
            "enum": ["full", "surname", "none"],
            "description": "Whether a `narrator` guess names a narrator of the work's best-agreeing recording: by surname and first name, by surname only, or not at all. Omitted unless `narrator` was given and a recording of the work credits narrators."
          },
          "language": {
            "type": "string",
            "enum": ["same", "other"],
            "description": "Whether the work's language is the stated `language`. Omitted unless both are known."
          }
        }
      },
      "PersonResult": {
        "type": "object",
        "description": "A search hit that is a person.",
        "required": ["kind", "id", "name"],
        "properties": {
          "kind": { "type": "string", "const": "person" },
          "id": { "type": "string" },
          "name": { "type": "string" }
        }
      },
      "SeriesResult": {
        "type": "object",
        "description": "A search hit that is a series, with its member count and what it is. Several series can share a name - an original and its translated editions, or a reading-order view of a franchise - and `language`, `translation_of` and `ordering_of` are what tell them apart on a list. Those fields need artifact version 7 and are omitted against an older one.",
        "required": ["kind", "id", "name", "works"],
        "properties": {
          "kind": { "type": "string", "const": "series" },
          "id": { "type": "string" },
          "name": { "type": "string" },
          "works": { "type": "integer", "description": "How many works the series holds." },
          "language": {
            "type": "string",
            "description": "The series' DERIVED language: the primary subtag most of its members share. Omitted when they tie, and against an artifact older than the languages layer.",
            "examples": ["en"]
          },
          "ordering": {
            "$ref": "#/components/schemas/Ordering",
            "description": "Which reading order this series' positions state. Omitted when unstated."
          },
          "ordering_of": {
            "type": "string",
            "description": "Set only on a VARIANT ordering: the slug of the franchise's primary series, as `SeriesDetail.ordering_of` spells it. Omitted for a primary.",
            "examples": ["the-stormlight-archive"]
          },
          "ordering_of_name": {
            "type": "string",
            "description": "The name of the primary series `ordering_of` names, so a list can say which franchise a variant orders without a second request. Present whenever `ordering_of` names a series the artifact carries, which in a validated catalogue is every variant.",
            "examples": ["The Stormlight Archive"]
          },
          "translation_of": {
            "type": "array",
            "description": "The series this one translates, in id order - the same list `SeriesDetail.translation_of` carries. Omitted when none.",
            "items": { "$ref": "#/components/schemas/SeriesTranslation" }
          }
        }
      },
      "SearchResult": {
        "description": "One search hit. Branch on `kind`.",
        "oneOf": [
          { "$ref": "#/components/schemas/WorkResult" },
          { "$ref": "#/components/schemas/PersonResult" },
          { "$ref": "#/components/schemas/SeriesResult" }
        ],
        "discriminator": {
          "propertyName": "kind",
          "mapping": {
            "work": "#/components/schemas/WorkResult",
            "person": "#/components/schemas/PersonResult",
            "series": "#/components/schemas/SeriesResult"
          }
        }
      },
      "Position": {
        "type": "object",
        "description": "A logical, EDITION-INDEPENDENT position in the work: the work chapter, 1-based, with 0 meaning front matter or knowledge from earlier books. A consumer maps its own recording timeline onto these ordinals.",
        "required": ["chapter"],
        "properties": {
          "chapter": { "type": "integer", "minimum": 0 }
        }
      },
      "ASINRef": {
        "type": "object",
        "description": "One marketplace's ASIN for a recording. A production sold in several marketplaces stays ONE recording; the region rides on the identifier.",
        "required": ["region", "asin"],
        "properties": {
          "region": { "type": "string", "examples": ["us"] },
          "asin": { "type": "string", "examples": ["B08G9PRS1K"] }
        }
      },
      "PurchaseLink": {
        "type": "object",
        "additionalProperties": false,
        "description": "A non-affiliate retailer URL derived from a recording identifier, or a store product page the recording states. It is a convenient route to check the retailer, not a claim that the product is currently listed, licensed for the visitor, or in stock. A LibriVox recording's catalogue page leads the list, marked `free`; the stated store pages (Audiobook Guild, GraphicAudio) follow it, ahead of the derived Audible and Libro.fm routes.",
        "required": ["retailer", "id", "url", "availability"],
        "properties": {
          "retailer": { "type": "string", "enum": ["librivox", "audiobookguild", "graphicaudio", "audible", "libro-fm"], "description": "Treat an unknown value as a retailer name to display: new retailers are added without a version change." },
          "id": { "type": "string", "description": "The source identifier: a LibriVox project id, an ASIN for Audible or a 13-digit recording ISBN for Libro.fm. A store page has no identifier, so its id is the page URL itself." },
          "region": { "type": "string", "description": "Audible marketplace region. Omitted for an unscoped recording ISBN." },
          "url": { "type": "string", "format": "uri", "description": "Derived non-affiliate URL containing no tracking parameters, or the store page as the store states it." },
          "availability": { "type": "string", "enum": ["unknown"], "description": "The catalogue does not persist volatile retailer availability." },
          "free": { "type": "boolean", "description": "Present only when TRUE: the recording is free to listen to and download (LibriVox, public domain)." }
        }
      },
      "WorkXref": {
        "type": "object",
        "description": "Cross-references to other databases, and the PRINT ISBNs of the abstract work (a recording's own ISBNs live on the recording). Every field is omitted when unknown; the object itself is omitted when all of them are.",
        "properties": {
          "wikidata": { "type": "string", "examples": ["Q100000"] },
          "openlibrary": { "type": "string" },
          "goodreads": { "type": "string" },
          "isbn": { "type": "array", "items": { "type": "string" } }
        }
      },
      "RecordingSummary": {
        "type": "object",
        "required": [
          "id",
          "narrators"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique within its work.",
            "examples": [
              "ray-porter-2021"
            ]
          },
          "narrators": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PersonRef"
            }
          },
          "runtime_min": {
            "type": "integer",
            "description": "Runtime in minutes. Omitted when unknown."
          },
          "release_date": {
            "type": "string",
            "description": "`YYYY-MM-DD`, or a partial date. Omitted when unknown."
          },
          "publisher": {
            "type": "string",
            "description": "The publisher of record. Omitted when unknown."
          },
          "chapter_count": {
            "type": "integer",
            "description": "How many chapter marks this recording has; fetch them from /api/v1/works/{id}/recordings/{rid}/chapters."
          },
          "language": {
            "type": "string",
            "description": "The recording's stated language; omitted when unknown."
          },
          "abridgement": {
            "type": "string",
            "enum": [
              "abridged",
              "unabridged"
            ],
            "description": "Omitted when unknown. Explicit unabridgement needs artifact schema 13; on an older artifact only legacy true proves abridged, and false remains unknown."
          }
        }
      },
      "ListeningGuideEntry": {
        "type": "object",
        "required": [
          "position",
          "work",
          "recordings_total",
          "recordings",
          "recordings_limit"
        ],
        "properties": {
          "position": {
            "type": "string"
          },
          "work": {
            "$ref": "#/components/schemas/WorkCard"
          },
          "recordings_total": {
            "type": "integer"
          },
          "recordings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RecordingSummary"
            }
          },
          "recordings_limit": {
            "type": "integer",
            "const": 5
          }
        }
      },
      "RecordingCredit": {
        "type": "object",
        "required": [
          "work",
          "recording",
          "series"
        ],
        "properties": {
          "work": {
            "$ref": "#/components/schemas/WorkCard"
          },
          "recording": {
            "$ref": "#/components/schemas/RecordingSummary"
          },
          "series": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SeriesRef"
            }
          }
        }
      },
      "PersonRecordingsPage": {
        "type": "object",
        "required": [
          "recordings",
          "total",
          "limit",
          "offset"
        ],
        "properties": {
          "recordings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RecordingCredit"
            }
          },
          "total": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          }
        }
      },
      "SeriesListeningGuide": {
        "type": "object",
        "required": [
          "id",
          "name",
          "authors",
          "entries",
          "works_total",
          "limit",
          "offset"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "language": {
            "type": "string",
            "description": "DERIVED, not stated: the primary language subtag more of the series' members state than any other - a plurality, so it need not be over half. Omitted when the leading languages tie or no member states one.",
            "examples": [
              "en"
            ]
          },
          "ordering": {
            "$ref": "#/components/schemas/Ordering",
            "description": "Which reading order this series' positions state. Omitted when unstated."
          },
          "ordering_of": {
            "type": "string",
            "description": "Set only on a VARIANT ordering: the slug of the franchise's primary series. Omitted for a primary.",
            "examples": [
              "the-stormlight-archive"
            ]
          },
          "authors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PersonRef"
            }
          },
          "works_total": {
            "type": "integer",
            "description": "UNPAGED membership count."
          },
          "limit": {
            "type": "integer",
            "description": "The page size that was applied, default 50 and at most 100."
          },
          "offset": {
            "type": "integer"
          },
          "translation_of": {
            "type": "array",
            "description": "The series this one translates, by id. Omitted when none.",
            "items": {
              "$ref": "#/components/schemas/SeriesTranslation"
            }
          },
          "translations": {
            "type": "array",
            "description": "The series that translate this one, by id. Omitted when none.",
            "items": {
              "$ref": "#/components/schemas/SeriesTranslation"
            }
          },
          "orderings": {
            "type": "array",
            "description": "The whole ordering family this series belongs to: the primary first, then every variant ordering of it by id. The same list is served on the primary and on each variant, so a reader can switch between orders from any of them. Omitted when the series has no variant ordering.",
            "items": {
              "$ref": "#/components/schemas/SeriesOrdering"
            }
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListeningGuideEntry"
            }
          }
        }
      },
      "RecordingDetail": {
        "type": "object",
        "description": "One narration/production of a work. A work can have many (different narrators, or a full-cast dramatization), each with its own identifiers and chapters.",
        "required": ["id", "narrators", "asin", "isbn", "chapter_count"],
        "properties": {
          "id": { "type": "string", "description": "Unique within its work.", "examples": ["ray-porter-2021"] },
          "narrators": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PersonRef" }
          },
          "language": {"type": "string", "description": "The recording's stated language; omitted when unknown."},
          "abridgement": {"type": "string", "enum": ["abridged", "unabridged"], "description": "Omitted when unknown. Explicit unabridgement needs artifact schema 13; on an older artifact only legacy true proves abridged, and false remains unknown."},
          "abridged": {
            "type": "boolean",
            "description": "Present only when TRUE. An absent key means unabridged or unstated - the underlying field is deliberately tri-state, and nothing guesses it."
          },
          "runtime_min": { "type": "integer", "description": "Runtime in minutes. Omitted when unknown." },
          "release_date": { "type": "string", "description": "`YYYY-MM-DD`, or a partial date. Omitted when unknown." },
          "publisher": { "type": "string", "description": "The publisher of record. Omitted when unknown." },
          "asin": {
            "type": "array",
            "description": "Region-scoped Audible identifiers. Never null; empty when none.",
            "items": { "$ref": "#/components/schemas/ASINRef" }
          },
          "isbn": {
            "type": "array",
            "description": "The recording's own ISBNs, bare. Never null; empty when none. A stated marketplace is deliberately not carried here - this answers \"which recording\", not \"which marketplace\".",
            "items": { "type": "string" }
          },
          "purchase_links": {
            "type": "array",
            "description": "Derived at response time from this recording's LibriVox page, store pages (`links`), ASINs and 13-digit ISBNs. Omitted when there are none; availability is deliberately not asserted.",
            "items": { "$ref": "#/components/schemas/PurchaseLink" }
          },
          "cover_url": { "type": "string", "description": "Remote cover URL. Omitted when none." },
          "librivox_id": { "type": "integer", "description": "The LibriVox project id of a LibriVox recording. Omitted otherwise. Needs artifact version 8." },
          "archive_id": { "type": "string", "description": "The Internet Archive item holding a LibriVox recording's files. Omitted when unstated." },
          "links": {
            "type": "object",
            "description": "Where the recording is published: a LibriVox recording's links, and the product page in a store that sells the recording (`audiobookguild`, `graphicaudio`), each omitted when unstated; the object itself is omitted when all are.",
            "properties": {
              "librivox": { "type": "string", "format": "uri", "description": "The LibriVox catalogue page." },
              "zip": { "type": "string", "format": "uri", "description": "The whole recording as one zip download." },
              "rss": { "type": "string", "format": "uri", "description": "The recording's podcast feed." },
              "text": { "type": "string", "format": "uri", "description": "The public-domain text it was read from." },
              "audiobookguild": { "type": "string", "format": "uri", "description": "The recording's product page on the Audiobook Guild store (audiobookguild.com), as the store states it. Needs artifact version 11." },
              "graphicaudio": { "type": "string", "format": "uri", "description": "The recording's product page on the GraphicAudio store (graphicaudio.net), as the store states it. Needs artifact version 11." }
            }
          },
          "copyright_year": { "type": "integer", "description": "The year the source text was first published or copyrighted, as LibriVox states it; negative for a year BC. Omitted when unstated." },
          "chapter_count": {
            "type": "integer",
            "description": "How many chapter marks this recording has; fetch them from /api/v1/works/{id}/recordings/{rid}/chapters."
          }
        }
      },
      "LibrivoxAudiobook": {
        "type": "object",
        "description": "One LibriVox project in LibriVox's own feed shape. Values are strings where LibriVox sends strings (ids, years, counts). `url_iarchive`, `sections`, `genres` and `translators` appear with `extended=1`; the three `coverart_` fields with `coverart=1`; `fields` keeps only the named ones.",
        "properties": {
          "id": { "type": "string", "examples": ["52"] },
          "title": { "type": "string" },
          "description": { "type": "string", "description": "Always empty: the mirror keeps no publisher or volunteer prose." },
          "url_text_source": { "type": "string" },
          "language": { "type": "string", "description": "LibriVox's language name.", "examples": ["English"] },
          "copyright_year": { "type": "string", "description": "`0` when unstated, as LibriVox sends it." },
          "num_sections": { "type": "string" },
          "url_rss": { "type": "string" },
          "url_zip_file": { "type": "string" },
          "url_project": { "type": "string", "description": "Always empty." },
          "url_librivox": { "type": "string" },
          "url_other": { "type": "string", "description": "Always empty." },
          "totaltime": { "type": "string", "examples": ["5:39:12"] },
          "totaltimesecs": { "type": "integer" },
          "authors": { "type": "array", "items": {
                "type": "object",
                "properties": {
                  "id": { "type": "string" },
                  "first_name": { "type": "string" },
                  "last_name": { "type": "string" },
                  "dob": { "type": "string", "description": "Birth year, or empty." },
                  "dod": { "type": "string", "description": "Death year, or empty." }
                }
              } },
          "url_iarchive": { "type": "string" },
          "coverart_jpg": { "type": ["string", "null"] },
          "coverart_pdf": { "type": ["string", "null"], "description": "Always null." },
          "coverart_thumbnail": { "type": ["string", "null"], "description": "Always null." },
          "sections": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "description": "Always empty." },
                "section_number": { "type": "string", "description": "LibriVox's own section number (some projects count from 0); on an artifact older than version 9, the 1-based position." },
                "title": { "type": "string" },
                "listen_url": { "type": "string" },
                "language": { "type": "string" },
                "playtime": { "type": "string", "description": "Seconds." },
                "file_name": { "type": "null", "description": "Always null: `listen_url` names the file." },
                "readers": {
                  "type": "array",
                  "description": "The section's own readers; for a recording read by one narrator throughout, that narrator. On an artifact older than version 9, the recording's one narrator, or empty for a recording read by several.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "reader_id": { "type": "string" },
                      "display_name": { "type": "string" }
                    }
                  }
                }
              }
            }
          },
          "genres": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "description": "Always empty." },
                "name": { "type": "string", "description": "LibriVox's genre name; on an artifact older than version 9, a genre of this project's vocabulary." }
              }
            }
          },
          "translators": { "type": "array", "items": {
                "type": "object",
                "properties": {
                  "id": { "type": "string" },
                  "first_name": { "type": "string" },
                  "last_name": { "type": "string" },
                  "dob": { "type": "string", "description": "Birth year, or empty." },
                  "dod": { "type": "string", "description": "Death year, or empty." }
                }
              } }
        }
      },
      "Character": {
        "type": "object",
        "description": "A community-authored, spoiler-gated character entry (CC BY-SA 4.0). Recurring characters are re-described per book, so spoilers stay bounded by which book the reader is in.",
        "required": ["id", "name", "reveal"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique within this work, NOT globally - two works may each have a `bilbo-baggins`.",
            "examples": ["ryland-grace"]
          },
          "name": { "type": "string" },
          "aliases": { "type": "array", "items": { "type": "string" } },
          "role": { "type": "string", "examples": ["protagonist"] },
          "reveal": {
            "description": "The spoiler gate: do not show this entry to a listener who has not reached this position.",
            "$ref": "#/components/schemas/Position"
          },
          "description": { "type": "string", "description": "Own-words description, length-capped by the authoring rules." },
          "xref": { "$ref": "#/components/schemas/CharacterXref" }
        }
      },
      "CharacterXref": {
        "type": "object",
        "description": "Cross-references for a character. A shared `wikidata` QID is what links one recurring character across a series' per-work entries.",
        "properties": {
          "wikidata": { "type": "string" },
          "goodreads": { "type": "string" }
        }
      },
      "Recap": {
        "type": "object",
        "description": "A community-authored \"story so far\" (CC BY-SA 4.0), safe to show once the listener has finished `through`.",
        "required": ["through", "text"],
        "properties": {
          "through": {
            "description": "Safe to show once the listener has FINISHED this chapter. No two recaps of one work share it.",
            "$ref": "#/components/schemas/Position"
          },
          "scope": {
            "type": "string",
            "enum": ["book", "series"],
            "description": "`book` recaps this book so far; `series` recaps earlier books. A `series` entry at chapter 0 is the \"previously, in earlier books\" recap. Omitted when unstated."
          },
          "text": { "type": "string", "description": "Own-words recap, length-capped by the authoring rules." }
        }
      },
      "RecapSummary": {
        "type": "object",
        "description": "Whole-book summaries for a reader who has ALREADY FINISHED the book - both spoil the ending by design. The object is omitted when neither field exists.",
        "properties": {
          "in_short": { "type": "string", "description": "The whole arc in one paragraph, ending included." },
          "ending": { "type": "string", "description": "How the book closes, stated plainly. A crisp handoff into the sequel." }
        }
      },
      "CommunityDescription": {
        "type": "object",
        "description": "The community-written, SPOILER-FREE description of the work - what a stranger reads before deciding to listen. Distinct from `description`, which is the CC0 record's own field: this text is CC BY-SA 4.0, so the two are never merged into one key. Omitted when the work has none, or the loaded artifact predates descriptions.",
        "required": ["text"],
        "properties": {
          "text": { "type": "string", "description": "Own words, no reveal past the opening act, never a rewritten publisher blurb." },
          "license": { "type": "string", "description": "The share-alike licence the text travels under.", "examples": ["CC-BY-SA-4.0"] }
        }
      },
      "WorkDetail": {
        "type": "object",
        "description": "The full work document. `characters`, `recaps`, `recap_summary`, `community_description`, `position_scale`, `genres`, `translation_of`, `translations` and `alternate_titles` are additionally gated on the loaded artifact's internal schema version: a server briefly serving an older artifact omits them rather than failing.",
        "required": ["id", "title", "authors", "language", "series", "recordings"],
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "subtitle": { "type": "string", "description": "Omitted when none." },
          "alternate_titles": {
            "type": "array",
            "description": "Other titles the book is published or known under (a retitled re-release, a regional title, another spelling), in the record's order; search finds the work by them. Omitted when none.",
            "items": { "type": "string" }
          },
          "authors": {
            "type": "array",
            "description": "The identity author list, in billing order.",
            "items": { "$ref": "#/components/schemas/PersonRef" }
          },
          "language": { "type": "string", "description": "BCP 47 language tag.", "examples": ["en"] },
          "first_published": { "type": "string", "description": "`YYYY` or `YYYY-MM-DD`. Omitted when unknown." },
          "description": { "type": "string", "description": "Community-written, never a publisher blurb. Omitted when none." },
          "genres": {
            "type": "array",
            "description": "Slugs from this project's own retailer-neutral vocabulary, ascending. Omitted when the work has none, or the loaded artifact predates genres.",
            "items": { "type": "string", "examples": ["hard-science-fiction"] }
          },
          "series": {
            "type": "array",
            "description": "EVERY series this work belongs to (the work card carries only the first). Every series that is not a variant reading order is listed before every variant one, then by series id. Never null; empty for a standalone.",
            "items": { "$ref": "#/components/schemas/SeriesRef" }
          },
          "translation_of": {
            "type": "array",
            "description": "The work(s) this one is a translation of, by id. Almost always one; a translated omnibus names every original it collects. Stated links only, never inferred. Omitted when none, or the loaded artifact predates version 7.",
            "items": { "$ref": "#/components/schemas/WorkTranslation" }
          },
          "translations": {
            "type": "array",
            "description": "The works that are translations of this one, by id. Omitted when none, or the loaded artifact predates version 7.",
            "items": { "$ref": "#/components/schemas/WorkTranslation" }
          },
          "xref": { "$ref": "#/components/schemas/WorkXref" },
          "recordings": {
            "type": ["array", "null"],
            "description": "Every known narration of this work. Null when the work has none recorded yet.",
            "items": { "$ref": "#/components/schemas/RecordingDetail" }
          },
          "characters": {
            "type": "array",
            "description": "The community character guide, in authored order. CC BY-SA 4.0. Omitted when the work has none.",
            "items": { "$ref": "#/components/schemas/Character" }
          },
          "recaps": {
            "type": "array",
            "description": "The community story-so-far recaps, ordered by position. CC BY-SA 4.0. Omitted when the work has none.",
            "items": { "$ref": "#/components/schemas/Recap" }
          },
          "recap_summary": { "$ref": "#/components/schemas/RecapSummary" },
          "community_description": { "$ref": "#/components/schemas/CommunityDescription" },
          "position_scale": { "$ref": "#/components/schemas/PositionScale" }
        }
      },
      "PositionScale": {
        "type": "object",
        "description": "The ruler a work's `characters` and `recaps` are numbered on: the book's length in these units. Use it to place a `reveal` or `through` position on a recording whose tracks are finer or coarser than the book's units. Omitted when the work states none, in which case positions are the book's own chapters with no stated length.",
        "required": ["length", "unit"],
        "properties": {
          "length": { "type": "integer", "minimum": 1, "description": "The book's whole length in `unit`s, whether or not the sidecars reach it.", "examples": [5] },
          "unit": { "type": "string", "enum": ["act", "chapter", "entry", "episode", "letter", "part", "piece", "poem", "scene", "section", "track"], "description": "What one position counts." },
          "partial": { "type": "boolean", "description": "The sidecars stop short of `length` on purpose. Omitted when they span the book." }
        }
      },
      "WorkTranslation": {
        "type": "object",
        "description": "The other end of a work's translation link.",
        "required": ["id", "title", "language"],
        "properties": {
          "id": { "type": "string", "examples": ["la-voie-des-rois"] },
          "title": { "type": "string", "examples": ["La Voie des rois"] },
          "language": { "type": "string", "description": "BCP 47 language tag.", "examples": ["fr"] }
        }
      },
      "Chapter": {
        "type": "object",
        "description": "One chapter mark of a recording. These are the RECORDING's timeline, not the edition-independent Position the community layer uses.",
        "required": ["title", "start_ms", "length_ms"],
        "properties": {
          "title": { "type": "string", "examples": ["Chapter 1"] },
          "start_ms": { "type": "integer", "description": "Offset from the start of the recording, milliseconds." },
          "length_ms": { "type": "integer", "description": "Chapter length, milliseconds." },
          "audio_url": { "type": "string", "format": "uri", "description": "The chapter's own audio file, for a LibriVox recording (one file per section). Omitted otherwise." }
        }
      },
      "NarratedEntry": {
        "type": "object",
        "description": "One narration credit: which recording of which work. A person who narrated two recordings of one work appears twice.",
        "required": ["work", "recording_id"],
        "properties": {
          "work": { "$ref": "#/components/schemas/WorkCard" },
          "recording_id": { "type": "string" }
        }
      },
      "PersonDetail": {
        "type": "object",
        "required": ["id", "name", "authored", "narrated", "authored_total", "narrated_total", "limit", "offset"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "sort_name": { "type": "string", "description": "Surname-first form, when recorded. Omitted otherwise." },
          "authored": {
            "type": "array",
            "description": "One page of works authored, by title.",
            "items": { "$ref": "#/components/schemas/WorkCard" }
          },
          "narrated": {
            "type": "array",
            "description": "One page of narration credits, by work title.",
            "items": { "$ref": "#/components/schemas/NarratedEntry" }
          },
          "authored_total": { "type": "integer", "description": "UNPAGED count of authored works." },
          "narrated_total": { "type": "integer", "description": "UNPAGED count of narration credits." },
          "translated": { "type": "array", "items": { "$ref": "#/components/schemas/NarratedEntry" }, "description": "The recordings this person is credited on as translator in the recording's own credits (a LibriVox project's translator), paged like `narrated`. Omitted when there are none, on an artifact older than version 9, and on a page past the list's end (`translated_total` is still present there). A translator a work credits is in `authored` already." },
          "translated_total": { "type": "integer", "description": "UNPAGED count of recording translator credits. Omitted when there are none and on an artifact older than version 9." },
          "limit": { "type": "integer", "description": "The window that was applied to each list." },
          "offset": { "type": "integer" }
        }
      },
      "SeriesEntry": {
        "type": "object",
        "required": ["position", "work"],
        "properties": {
          "position": {
            "type": "string",
            "description": "The volume position as a string: \"2\", \"2.5\", or an omnibus range \"1-3.5\".",
            "examples": ["2"]
          },
          "work": { "$ref": "#/components/schemas/WorkCard" }
        }
      },
      "SeriesDetail": {
        "type": "object",
        "description": "A series and its member works. `language`, `ordering`, `ordering_of`, `translation_of`, `translations` and `orderings` need artifact version 7; a server briefly serving an older artifact omits them rather than failing.",
        "required": ["id", "name", "authors", "works", "works_total", "limit", "offset"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "language": {
            "type": "string",
            "description": "DERIVED, not stated: the primary language subtag more of the series' members state than any other - a plurality, so it need not be over half. Omitted when the leading languages tie or no member states one.",
            "examples": ["en"]
          },
          "ordering": {
            "$ref": "#/components/schemas/Ordering",
            "description": "Which reading order this series' positions state. Omitted when unstated."
          },
          "ordering_of": {
            "type": "string",
            "description": "Set only on a VARIANT ordering: the slug of the franchise's primary series. Omitted for a primary.",
            "examples": ["the-stormlight-archive"]
          },
          "authors": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PersonRef" }
          },
          "works": {
            "type": "array",
            "description": "Member works in position order.",
            "items": { "$ref": "#/components/schemas/SeriesEntry" }
          },
          "works_total": { "type": "integer", "description": "UNPAGED membership count." },
          "limit": { "type": "integer", "description": "The window that was applied. 0 means the whole series was returned - the default." },
          "offset": { "type": "integer" },
          "translation_of": {
            "type": "array",
            "description": "The series this one translates, by id. Omitted when none.",
            "items": { "$ref": "#/components/schemas/SeriesTranslation" }
          },
          "translations": {
            "type": "array",
            "description": "The series that translate this one, by id. Omitted when none.",
            "items": { "$ref": "#/components/schemas/SeriesTranslation" }
          },
          "orderings": {
            "type": "array",
            "description": "The whole ordering family this series belongs to: the primary first, then every variant ordering of it by id. The same list is served on the primary and on each variant, so a reader can switch between orders from any of them. Omitted when the series has no variant ordering.",
            "items": { "$ref": "#/components/schemas/SeriesOrdering" }
          }
        }
      },
      "SeriesTranslation": {
        "type": "object",
        "description": "The other end of a series' translation link.",
        "required": ["id", "name"],
        "properties": {
          "id": { "type": "string", "examples": ["die-sturmlicht-chroniken"] },
          "name": { "type": "string", "examples": ["Die Sturmlicht-Chroniken"] },
          "language": { "type": "string", "description": "That series' derived language. Omitted when its members tie.", "examples": ["de"] }
        }
      },
      "SeriesOrdering": {
        "type": "object",
        "description": "One member of an ordering family.",
        "required": ["id", "name"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "ordering": {
            "$ref": "#/components/schemas/Ordering",
            "description": "The reading order that series states. Omitted when unstated."
          }
        }
      },
      "Ordering": {
        "type": "string",
        "enum": ["publication", "chronological", "recommended"],
        "description": "A series' reading order. An author's preferred order and a recommended listening order are both `recommended`; the series name keeps the exact wording."
      },
      "LookupResult": {
        "type": "object",
        "required": ["work", "recording_id"],
        "properties": {
          "work": { "$ref": "#/components/schemas/WorkCard" },
          "recording_id": {
            "type": "string",
            "description": "The recording the identifier names. Empty in the rare case where a work print ISBN matched a work with no recordings."
          }
        }
      },
      "CoverageTotals": {
        "type": "object",
        "description": "An omitted sidecar count means the dimension is not evaluable against the loaded artifact - distinct from a real `0`.",
        "required": ["works"],
        "properties": {
          "works": { "type": "integer" },
          "with_characters": { "type": "integer" },
          "with_recaps": { "type": "integer" },
          "with_recap_summary": { "type": "integer" },
          "with_descriptions": { "type": "integer", "description": "Works carrying the community spoiler-free description. Needs artifact version 6." }
        }
      },
      "CoverageResult": {
        "type": "object",
        "required": ["totals"],
        "properties": {
          "totals": { "$ref": "#/components/schemas/CoverageTotals" }
        }
      },
      "CoverageWork": {
        "type": "object",
        "required": ["id", "title", "language", "authors", "missing"],
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "language": {
            "type": "string",
            "description": "BCP 47 language tag. Always present - every work states one.",
            "examples": ["en"]
          },
          "authors": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PersonRef" }
          },
          "series": {
            "description": "Omitted for a standalone work.",
            "$ref": "#/components/schemas/SeriesRef"
          },
          "missing": {
            "type": "array",
            "description": "Which parts of the community layer the work still lacks, in a fixed order. Empty when it lacks none.",
            "items": {
              "type": "string",
              "enum": ["characters", "recaps", "recap_summary", "description"]
            }
          }
        }
      },
      "CoverageWorksResult": {
        "type": "object",
        "required": ["works", "total", "limit", "offset", "available"],
        "properties": {
          "works": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/CoverageWork" }
          },
          "total": { "type": "integer", "description": "UNPAGED count for this filter." },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "available": {
            "type": "boolean",
            "description": "False when this filter's dimension cannot be evaluated against the loaded artifact; `works` is then empty and `total` 0."
          }
        }
      },
      "SeriesGap": {
        "type": "object",
        "required": ["id", "name", "present", "missing_positions"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "present": {
            "type": "array",
            "description": "The raw position strings the series does hold, in numeric order.",
            "items": { "type": "string" }
          },
          "missing_positions": {
            "type": "array",
            "description": "The integer positions absent strictly between the lowest and highest present one.",
            "items": { "type": "integer" }
          }
        }
      },
      "SeriesGapsResult": {
        "type": "object",
        "required": ["gaps", "total", "limit", "offset"],
        "properties": {
          "gaps": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/SeriesGap" }
          },
          "total": { "type": "integer", "description": "UNPAGED count of series with gaps." },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" }
        }
      },
      "ABSSeriesRef": {
        "type": "object",
        "description": "Audiobookshelf's series shape.",
        "required": ["series"],
        "properties": {
          "series": { "type": "string" },
          "sequence": { "type": "string", "description": "The position string, passed through as-is. Omitted when empty." }
        }
      },
      "ABSBook": {
        "type": "object",
        "description": "Audiobookshelf's BookMetadata shape - NOT this API's work shape. One entry per recording. Only `title` is guaranteed; every other field is omitted when empty.",
        "required": ["title"],
        "properties": {
          "title": { "type": "string" },
          "subtitle": { "type": "string" },
          "author": { "type": "string", "description": "Author names, comma-joined." },
          "narrator": { "type": "string", "description": "Narrator names, comma-joined." },
          "publisher": { "type": "string" },
          "publishedYear": { "type": "string", "description": "A bare 4-digit year, as a string." },
          "description": { "type": "string", "description": "The community's own-words, spoiler-free description where the work carries one, else the CC0 record's own. A community description arrives with a plain-text attribution line appended - `(Description CC BY-SA 4.0, AudioSilo Meta community)` - because this shape has no license field and the text is share-alike; the CC0 fallback carries no such line. Use `community_description` on `GET /api/v1/works/{id}` instead if you need the text and its license as separate fields." },
          "cover": { "type": "string", "description": "Remote cover URL." },
          "isbn": { "type": "string", "description": "The recording's first ISBN, else the work's first print ISBN." },
          "asin": { "type": "string", "description": "The us-region ASIN when there is one, else the first available." },
          "genres": {
            "type": "array",
            "description": "Human-facing display LABELS (\"Hard Science Fiction\"), not the slugs the JSON API serves.",
            "items": { "type": "string" }
          },
          "tags": {
            "type": "array",
            "description": "Never populated: the data model has no tag concept.",
            "items": { "type": "string" }
          },
          "series": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ABSSeriesRef" }
          },
          "language": { "type": "string" },
          "duration": { "type": "integer", "description": "Runtime in MINUTES, which is what Audiobookshelf expects here." }
        }
      },
      "ABSSearchResult": {
        "type": "object",
        "required": ["matches"],
        "properties": {
          "matches": {
            "type": "array",
            "description": "Always an array - Audiobookshelf hard-fails if it is missing or not one.",
            "items": { "$ref": "#/components/schemas/ABSBook" }
          }
        }
      },
      "ReleaseWebhook": {
        "type": "object",
        "description": "A GitHub release event. Only these fields are read; everything else in a real GitHub payload is ignored. The body is a trigger only - the server re-queries GitHub for the release it acts on.",
        "properties": {
          "action": { "type": "string", "description": "Only `published` triggers a refresh.", "examples": ["published"] },
          "repository": {
            "type": "object",
            "properties": {
              "full_name": {
                "type": "string",
                "description": "Must match the deployment's configured repository, case-insensitively.",
                "examples": ["KodeStar/audiosilo-meta"]
              }
            }
          }
        }
      }
    }
  }
}
