Skip to content
Developers

API reference

The API over the AudioSilo community audiobook metadata database.

Base URL
https://meta.audiosilo.app
Auth
None to read the catalogue
CORS
Open on catalogue reads
Writes
None to the catalogue

An API over a compiled snapshot of the community metadata database at https://github.com/kodestar/audiosilo-meta.

Everything 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.)

The 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.

The 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.

The 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.

Some 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.

Slugs 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.

Licensing: 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.

Response shapes below are JSON skeletons whose values are types, not data:

"key"
always present
"key?"
omitted when empty or unknown
| null
the key is present, the value may be null
<A | B>
one of those shapes - each is documented under the endpoint that returns it

Works

Work documents: the abstract book, its recordings, and the community expressive layer.

GET /api/v1/works/latest

Recently added works

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

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

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 In Type Notes
limit query integer default 12, 1-50 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.
lang query string 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.
source query string 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.

Responses

200 The newest work cards.
{
  "works": [
    {
      "id": string,
      "title": string,
      "authors": [
        {
          "id": string,
          "name": string
        }
      ],
      "language": string,
      "series": {
        "id": string,
        "name": string,
        "position": string,
        "ordering_of?": string
      } | null,
      "release_date?": string,
      "cover_url": string | null,
      "added_at": string | null
    }
  ]
}
400 A lang item is not a language tag, or source names no source type.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}
GET /api/v1/works/{id}

One work in full

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

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

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

Parameters

Name In Type Notes
id * path string The work's slug, e.g. project-hail-mary.

* required

Responses

200 The work document.
{
  "id": string,
  "title": string,
  "subtitle?": string,
  "alternate_titles?": [
    string
  ],
  "authors": [
    {
      "id": string,
      "name": string
    }
  ],
  "language": string,
  "first_published?": string,
  "description?": string,
  "genres?": [
    string
  ],
  "series": [
    {
      "id": string,
      "name": string,
      "position": string,
      "ordering_of?": string
    }
  ],
  "translation_of?": [
    {
      "id": string,
      "title": string,
      "language": string
    }
  ],
  "translations?": [
    {
      "id": string,
      "title": string,
      "language": string
    }
  ],
  "xref?": {
    "wikidata?": string,
    "openlibrary?": string,
    "goodreads?": string,
    "isbn?": [
      string
    ]
  },
  "recordings": [
    {
      "id": string,
      "narrators": [
        {
          "id": string,
          "name": string
        }
      ],
      "language?": string,
      "abridgement?": "abridged" | "unabridged",
      "abridged?": boolean,
      "runtime_min?": integer,
      "release_date?": string,
      "publisher?": string,
      "asin": [
        {
          "region": string,
          "asin": string
        }
      ],
      "isbn": [
        string
      ],
      "purchase_links?": [
        {
          "retailer": "librivox" | "audiobookguild" | "graphicaudio" | "audible" | "libro-fm",
          "id": string,
          "region?": string,
          "url": string,
          "availability": "unknown",
          "free?": boolean
        }
      ],
      "cover_url?": string,
      "librivox_id?": integer,
      "archive_id?": string,
      "links?": {
        "librivox?": string,
        "zip?": string,
        "rss?": string,
        "text?": string,
        "audiobookguild?": string,
        "graphicaudio?": string
      },
      "copyright_year?": integer,
      "chapter_count": integer
    }
  ] | null,
  "characters?": [
    {
      "id": string,
      "name": string,
      "aliases?": [
        string
      ],
      "role?": string,
      "reveal": {
        "chapter": integer
      },
      "description?": string,
      "xref?": {
        "wikidata?": string,
        "goodreads?": string
      }
    }
  ],
  "recaps?": [
    {
      "through": {
        "chapter": integer
      },
      "scope?": "book" | "series",
      "text": string
    }
  ],
  "recap_summary?": {
    "in_short?": string,
    "ending?": string
  },
  "community_description?": {
    "text": string,
    "license?": string
  },
  "position_scale?": {
    "length": integer,
    "unit": "act" | "chapter" | "entry" | "episode" | "letter" | "part" | "piece" | "poem" | "scene" | "section" | "track",
    "partial?": boolean
  }
}
301 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.
{
  "redirect": string
}
404 No such record.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}
GET /api/v1/works/{id}/recordings/{rid}/chapters

One recording's chapter list

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

Name In Type Notes
id * path string The work's slug, e.g. project-hail-mary.
rid * path string The recording's slug, unique within its work, e.g. ray-porter-2021.

* required

Responses

200 The recording's chapters (empty when it has none, or does not exist).
{
  "chapters": [
    {
      "title": string,
      "start_ms": integer,
      "length_ms": integer,
      "audio_url?": string
    }
  ]
}
301 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.
{
  "redirect": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}

People & Series

A person's credits and a series' member works, both windowed with unpaged totals.

GET /api/v1/people/{id}

One person and a page of their credits

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

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

Parameters

Name In Type Notes
id * path string The person's slug, e.g. ray-porter.
limit query integer default 100, 1-500 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.
offset query integer default 0, min 0 Rows to skip. A negative or non-numeric value is treated as 0.

* required

Responses

200 The person and one page of each credit list.
{
  "id": string,
  "name": string,
  "sort_name?": string,
  "authored": [
    {
      "id": string,
      "title": string,
      "authors": [
        {
          "id": string,
          "name": string
        }
      ],
      "language": string,
      "series": {
        "id": string,
        "name": string,
        "position": string,
        "ordering_of?": string
      } | null,
      "release_date?": string,
      "cover_url": string | null,
      "added_at": string | null
    }
  ],
  "narrated": [
    {
      "work": {
        "id": string,
        "title": string,
        "authors": [
          {
            "id": string,
            "name": string
          }
        ],
        "language": string,
        "series": {
          "id": string,
          "name": string,
          "position": string,
          "ordering_of?": string
        } | null,
        "release_date?": string,
        "cover_url": string | null,
        "added_at": string | null
      },
      "recording_id": string
    }
  ],
  "authored_total": integer,
  "narrated_total": integer,
  "translated?": [
    {
      "work": {
        "id": string,
        "title": string,
        "authors": [
          {
            "id": string,
            "name": string
          }
        ],
        "language": string,
        "series": {
          "id": string,
          "name": string,
          "position": string,
          "ordering_of?": string
        } | null,
        "release_date?": string,
        "cover_url": string | null,
        "added_at": string | null
      },
      "recording_id": string
    }
  ],
  "translated_total?": integer,
  "limit": integer,
  "offset": integer
}
301 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.
{
  "redirect": string
}
404 No such record.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}
GET /api/v1/series/{id}

One series and its member works

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

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

Parameters

Name In Type Notes
id * path string The series' slug, e.g. the-stormlight-archive.
limit query integer 1-500 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.
offset query integer default 0, min 0 Rows to skip. A negative or non-numeric value is treated as 0.

* required

Responses

200 The series and its member works.
{
  "id": string,
  "name": string,
  "language?": string,
  "ordering?": "publication" | "chronological" | "recommended",
  "ordering_of?": string,
  "authors": [
    {
      "id": string,
      "name": string
    }
  ],
  "works": [
    {
      "position": string,
      "work": {
        "id": string,
        "title": string,
        "authors": [
          {
            "id": string,
            "name": string
          }
        ],
        "language": string,
        "series": {
          "id": string,
          "name": string,
          "position": string,
          "ordering_of?": string
        } | null,
        "release_date?": string,
        "cover_url": string | null,
        "added_at": string | null
      }
    }
  ],
  "works_total": integer,
  "limit": integer,
  "offset": integer,
  "translation_of?": [
    {
      "id": string,
      "name": string,
      "language?": string
    }
  ],
  "translations?": [
    {
      "id": string,
      "name": string,
      "language?": string
    }
  ],
  "orderings?": [
    {
      "id": string,
      "name": string,
      "ordering?": "publication" | "chronological" | "recommended"
    }
  ]
}
301 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.
{
  "redirect": string
}
404 No such record.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}
GET /api/v1/series/{id}/listening-guide

One page of a series listening guide

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 In Type Notes
id * path string The record slug. Retired slugs redirect at this same route.
limit query integer default 50, 1-100 Page size, default 50 and at most 100. Invalid or non-positive values use the default.
offset query integer default 0, min 0 Rows to skip. A negative or non-numeric value is treated as 0.

* required

Responses

200 One page of a series listening guide.
{
  "id": string,
  "name": string,
  "language?": string,
  "ordering?": "publication" | "chronological" | "recommended",
  "ordering_of?": string,
  "authors": [
    {
      "id": string,
      "name": string
    }
  ],
  "works_total": integer,
  "limit": integer,
  "offset": integer,
  "translation_of?": [
    {
      "id": string,
      "name": string,
      "language?": string
    }
  ],
  "translations?": [
    {
      "id": string,
      "name": string,
      "language?": string
    }
  ],
  "orderings?": [
    {
      "id": string,
      "name": string,
      "ordering?": "publication" | "chronological" | "recommended"
    }
  ],
  "entries": [
    {
      "position": string,
      "work": {
        "id": string,
        "title": string,
        "authors": [
          {
            "id": string,
            "name": string
          }
        ],
        "language": string,
        "series": {
          "id": string,
          "name": string,
          "position": string,
          "ordering_of?": string
        } | null,
        "release_date?": string,
        "cover_url": string | null,
        "added_at": string | null
      },
      "recordings_total": integer,
      "recordings": [
        {
          "id": string,
          "narrators": [
            {
              "id": string,
              "name": string
            }
          ],
          "runtime_min?": integer,
          "release_date?": string,
          "publisher?": string,
          "chapter_count?": integer,
          "language?": string,
          "abridgement?": "abridged" | "unabridged"
        }
      ],
      "recordings_limit": 5
    }
  ]
}
301 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.
{
  "redirect": string
}
400 q was missing, empty or whitespace only.
{
  "error": string
}
404 No such record.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}
GET /api/v1/people/{id}/recordings

One page of narration recording credits

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 In Type Notes
id * path string The record slug. Retired slugs redirect at this same route.
limit query integer default 50, 1-100 Page size, default 50 and at most 100. Invalid or non-positive values use the default.
offset query integer default 0, min 0 Rows to skip. A negative or non-numeric value is treated as 0.
series query string An optional series slug. Invalid slugs are rejected.
lang query string Optional primary language subtag or comma-separated primary subtags. Invalid tags are rejected.

* required

Responses

200 One page of narration recording credits.
{
  "recordings": [
    {
      "work": {
        "id": string,
        "title": string,
        "authors": [
          {
            "id": string,
            "name": string
          }
        ],
        "language": string,
        "series": {
          "id": string,
          "name": string,
          "position": string,
          "ordering_of?": string
        } | null,
        "release_date?": string,
        "cover_url": string | null,
        "added_at": string | null
      },
      "recording": {
        "id": string,
        "narrators": [
          {
            "id": string,
            "name": string
          }
        ],
        "runtime_min?": integer,
        "release_date?": string,
        "publisher?": string,
        "chapter_count?": integer,
        "language?": string,
        "abridgement?": "abridged" | "unabridged"
      },
      "series": [
        {
          "id": string,
          "name": string,
          "position": string,
          "ordering_of?": string
        }
      ]
    }
  ],
  "total": integer,
  "limit": integer,
  "offset": integer
}
301 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.
{
  "redirect": string
}
400 q was missing, empty or whitespace only.
{
  "error": string
}
404 No such record.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}

Lookup

Exact identifier resolution: which recording an ASIN, ISBN or LibriVox project id names.

GET /api/v1/lookup

Resolve an ASIN, ISBN or LibriVox id to a recording

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.

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

Parameters

Name In Type Notes
asin query string An Audible ASIN, e.g. B08G9PRS1K. Takes precedence over isbn.
isbn query string A bare 10- or 13-digit ISBN, e.g. 9781427209269.
librivox_id query integer min 1 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.

Responses

200 The work and recording the identifier names.
{
  "work": {
    "id": string,
    "title": string,
    "authors": [
      {
        "id": string,
        "name": string
      }
    ],
    "language": string,
    "series": {
      "id": string,
      "name": string,
      "position": string,
      "ordering_of?": string
    } | null,
    "release_date?": string,
    "cover_url": string | null,
    "added_at": string | null
  },
  "recording_id": string
}
400 None of asin, isbn and librivox_id was supplied, or librivox_id is not a positive integer.
{
  "error": string
}
404 No such record.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}

LibriVox

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.

GET /api/v1/librivox/audiobooks

LibriVox-shaped audiobooks feed

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.

The 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.

On 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.

At most 500 projects a request. A reader that wants the whole catalogue should download the meta.sqlite.gz release asset instead.

Parameters

Name In Type Notes
id query integer min 1 One LibriVox project id. Not a positive integer is a 400.
since query integer min 0 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.
title query string 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.
author query string 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.
genre query string 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).
extended query string 1 adds url_iarchive, sections, genres and translators. Empty or 0 is off.
coverart query string 1 adds coverart_jpg, coverart_pdf and coverart_thumbnail. Empty or 0 is off.
fields query string Keep only these top-level fields: {id,title}, a comma list, or repeated as fields[].
limit query integer default 50, 0-500 How many projects to return: default 50, at most 500. Over 500 is a 400, as LibriVox answers; empty or 0 is the default.
offset query integer default 0, min 0 How many matching projects to skip. Not a non-negative integer is a 400.
sort_order query string desc orders by project id descending; anything else ascending.
format query "json" Only json (the default) is served. The XML, JSONP and PHP forms LibriVox offers are a 400.

Responses

200 One page of projects, in LibriVox's shape.
{
  "books": [
    {
      "id?": string,
      "title?": string,
      "description?": string,
      "url_text_source?": string,
      "language?": string,
      "copyright_year?": string,
      "num_sections?": string,
      "url_rss?": string,
      "url_zip_file?": string,
      "url_project?": string,
      "url_librivox?": string,
      "url_other?": string,
      "totaltime?": string,
      "totaltimesecs?": integer,
      "authors?": [
        {
          "id?": string,
          "first_name?": string,
          "last_name?": string,
          "dob?": string,
          "dod?": string
        }
      ],
      "url_iarchive?": string,
      "coverart_jpg?": string | null,
      "coverart_pdf?": string | null,
      "coverart_thumbnail?": string | null,
      "sections?": [
        {
          "id?": string,
          "section_number?": string,
          "title?": string,
          "listen_url?": string,
          "language?": string,
          "playtime?": string,
          "file_name?": any | null,
          "readers?": [
            {
              "reader_id?": string,
              "display_name?": string
            }
          ]
        }
      ],
      "genres?": [
        {
          "id?": string,
          "name?": string
        }
      ],
      "translators?": [
        {
          "id?": string,
          "first_name?": string,
          "last_name?": string,
          "dob?": string,
          "dod?": string
        }
      ]
    }
  ]
}
400 A parameter is malformed, limit is over 500, or format is not json.
{
  "error": string
}
404 No project matched, or the loaded artifact is older than version 8. The body is LibriVox's own: {"error": "Audiobooks could not be found"}.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}
GET /api/v1/librivox/audiobooks/

LibriVox-shaped audiobooks feed (trailing-slash spelling)

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 In Type Notes
id query integer min 1 One LibriVox project id. Not a positive integer is a 400.
since query integer min 0 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.
title query string 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.
author query string 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.
genre query string 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).
extended query string 1 adds url_iarchive, sections, genres and translators. Empty or 0 is off.
coverart query string 1 adds coverart_jpg, coverart_pdf and coverart_thumbnail. Empty or 0 is off.
fields query string Keep only these top-level fields: {id,title}, a comma list, or repeated as fields[].
limit query integer default 50, 0-500 How many projects to return: default 50, at most 500. Over 500 is a 400, as LibriVox answers; empty or 0 is the default.
offset query integer default 0, min 0 How many matching projects to skip. Not a non-negative integer is a 400.
sort_order query string desc orders by project id descending; anything else ascending.
format query "json" Only json (the default) is served. The XML, JSONP and PHP forms LibriVox offers are a 400.

Responses

200 One page of projects, in LibriVox's shape.
{
  "books": [
    {
      "id?": string,
      "title?": string,
      "description?": string,
      "url_text_source?": string,
      "language?": string,
      "copyright_year?": string,
      "num_sections?": string,
      "url_rss?": string,
      "url_zip_file?": string,
      "url_project?": string,
      "url_librivox?": string,
      "url_other?": string,
      "totaltime?": string,
      "totaltimesecs?": integer,
      "authors?": [
        {
          "id?": string,
          "first_name?": string,
          "last_name?": string,
          "dob?": string,
          "dod?": string
        }
      ],
      "url_iarchive?": string,
      "coverart_jpg?": string | null,
      "coverart_pdf?": string | null,
      "coverart_thumbnail?": string | null,
      "sections?": [
        {
          "id?": string,
          "section_number?": string,
          "title?": string,
          "listen_url?": string,
          "language?": string,
          "playtime?": string,
          "file_name?": any | null,
          "readers?": [
            {
              "reader_id?": string,
              "display_name?": string
            }
          ]
        }
      ],
      "genres?": [
        {
          "id?": string,
          "name?": string
        }
      ],
      "translators?": [
        {
          "id?": string,
          "first_name?": string,
          "last_name?": string,
          "dob?": string,
          "dod?": string
        }
      ]
    }
  ]
}
400 A parameter is malformed, limit is over 500, or format is not json.
{
  "error": string
}
404 No project matched, or the loaded artifact is older than version 8. The body is LibriVox's own: {"error": "Audiobooks could not be found"}.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}

Coverage

What the community layer still needs: expressive-layer totals, a filtered per-work browser, and series with missing volumes.

GET /api/v1/coverage

Expressive-layer totals

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 The top-line coverage totals.
{
  "totals": {
    "works": integer,
    "with_characters?": integer,
    "with_recaps?": integer,
    "with_recap_summary?": integer,
    "with_descriptions?": integer
  }
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}
GET /api/v1/coverage/works

Works by expressive-layer status

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

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

Parameters

Name In Type Notes
filter query "missing" | "has_characters" | "has_recaps" | "has_recap_summary" | "has_description" default "missing" Which works to list. An empty value means missing.
q query string 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.
lang query string 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.
limit query integer default 25, 1-100 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.
offset query integer default 0, min 0 Rows to skip. A negative or non-numeric value is treated as 0.

Responses

200 One page of works for the filter.
{
  "works": [
    {
      "id": string,
      "title": string,
      "language": string,
      "authors": [
        {
          "id": string,
          "name": string
        }
      ],
      "series?": {
        "id": string,
        "name": string,
        "position": string,
        "ordering_of?": string
      },
      "missing": [
        "characters" | "recaps" | "recap_summary" | "description"
      ]
    }
  ],
  "total": integer,
  "limit": integer,
  "offset": integer,
  "available": boolean
}
400 Unrecognized filter value, or a lang item that is not a language tag.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}
GET /api/v1/coverage/series-gaps

Series with missing volumes

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 In Type Notes
q query string Case-insensitive substring of the series name.
limit query integer default 25, 1-100 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.
offset query integer default 0, min 0 Rows to skip. A negative or non-numeric value is treated as 0.

Responses

200 One page of series with gaps.
{
  "gaps": [
    {
      "id": string,
      "name": string,
      "present": [
        string
      ],
      "missing_positions": [
        integer
      ]
    }
  ],
  "total": integer,
  "limit": integer,
  "offset": integer
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}

Watch feeds

Stateless notification feeds for a list of series carried in the request URL, as Atom, JSON Feed or a subscribable release calendar.

GET /api/v1/watch/feed.atom

Watched-series Atom feed

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

Name In Type Notes
s * query string 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.
window query integer default 90, 1-365 How many days of released or newly catalogued works to include. Future release dates are included regardless of this window.

* required

Responses

200 The Atom 1.0 feed.
string
304 The supplied If-None-Match validator still names this feed.
400 s is missing or invalid, contains more than 200 series, or window is outside 1-365.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}
GET /api/v1/watch/feed.json

Watched-series JSON Feed

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

Name In Type Notes
s * query string 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.
window query integer default 90, 1-365 How many days of released or newly catalogued works to include. Future release dates are included regardless of this window.

* required

Responses

200 The JSON Feed 1.1 document.
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "AudioSilo Meta: new in your series",
  "description": string,
  "feed_url": string,
  "items": [
    {
      "id": string,
      "url": string,
      "title": string,
      "content_text": string,
      "date_published": string,
      "date_modified": string,
      "authors?": [
        {
          "name": string
        }
      ],
      "tags": [
        "preorder" | "released" | "date unknown"
      ]
    }
  ]
}
304 The supplied If-None-Match validator still names this feed.
400 s is missing or invalid, contains more than 200 series, or window is outside 1-365.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}
GET /api/v1/watch/releases.ics

Watched-series release calendar

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

Parameters

Name In Type Notes
s * query string 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.
window query integer default 90, 1-365 How many days of released or newly catalogued works to include. Future release dates are included regardless of this window.

* required

Responses

200 The iCalendar document.
string
304 The supplied If-None-Match validator still names this calendar.
400 s is missing or invalid, contains more than 200 series, or window is outside 1-365.
{
  "error": string
}
429 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.
{
  "error": string
}
500 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.
{
  "error": string
}
503 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.
{
  "error": string
}

Audiobookshelf provider

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.

Server

Readiness, catalogue totals, this document, and the routes only a deployment that configures them serves: the release-notification hook and the intake queue.

GET /healthz

Readiness probe

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 An artifact is loaded and the API is answering.
{
  "status": "ok",
  "built_at": string,
  "works": integer
}
503 No artifact has loaded yet. Retry-After reports the wait the poll loop is actually on.
{
  "status": "starting"
}
GET /api/v1/openapi.json

This document

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

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

Responses

200 The OpenAPI 3.1 document.
{ ... }
304 The If-None-Match request header named the current ETag, so the copy the client holds is still the document. No body.
GET /api/v1/stats

Catalogue totals

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 The loaded artifact's totals.
{
  "works": integer,
  "recordings": integer,
  "people": integer,
  "series": integer,
  "total_runtime_min": integer,
  "total_chapters": integer,
  "built_at": string,
  "languages?": [
    {
      "language": string,
      "works": integer
    }
  ]
}
503 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.
{
  "error": string
}
GET /api/v1/intake/unknown-asins

Read the intake queue (token only)

Registered only when the deployment also sets METASERVE_INTAKE_TOKEN to a value of at least 32 bytes. The whole queue, bounded by its cap of 20,000 rows, ordered by count descending, then first day, then ASIN. A count is unverified: it orders work and says nothing about how many distinct servers reported an ASIN. There is no acknowledgement: a row leaves when a data release holds its ASIN, or when it expires. Every answer is Cache-Control: no-store, with no CORS headers.

Responses

200 The queue.
{
  "total": integer,
  "asins": [
    {
      "asin": string,
      "count": integer,
      "first_day": string,
      "last_day": string
    }
  ]
}
401 A missing or wrong bearer token. Carries WWW-Authenticate: Bearer.
{
  "error": string
}
429 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.
{
  "error": string
}
503 The queue could not be read.
{
  "error": string
}
POST /api/v1/intake/unknown-asins

Report ASINs the catalogue does not hold (optional)

Registered only when the deployment sets METASERVE_INTAKE_DB; elsewhere this route answers 404, which a client should read as not offered. It queues reported ASINs for later lookup. A report is a suggestion of where to look and never a record: nothing reaches the catalogue from here without a real retailer listing behind it.

The queue keeps each ASIN with a count of the reports naming it and the first and last UTC day it was reported, and no client address, timestamp, user agent or batch id. A report's other JSON members are ignored and never stored. To enforce the limit below, the server holds a client's address (an IPv6 address as its /64) in memory until about a day after its last request, refused or not.

This route carries no CORS headers and has no OPTIONS route, and application/json is required, so a script on another origin cannot get a report taken: a JSON request's preflight fails. A cross-origin POST a browser sends without a preflight has another Content-Type and answers 415 before the limit is consulted: nothing is stored and none of that client's six is spent. Every answer is Cache-Control: no-store.

The limit is 6 POSTs a day per client with a burst of 6, separate from the API's own limit, and refused reports count toward it, except a 415. Each ASIN must match ^[A-Z0-9]{10}$ exactly, so a lower-case spelling is invalid rather than normalized: send them upper case. One ASIN named twice in a body counts once, and one report adds 1 to each ASIN's count. A row leaves the queue when a newer data release holds that ASIN, after 90 days with no report, or when the queue is at its cap of 20,000 rows and a new ASIN evicts the lowest by count, then last day.

Request body

{
  "asins": [
    string
  ]
}

Responses

202 Taken. An empty asins array is 202 with three zeros.
{
  "accepted": integer,
  "known": integer,
  "invalid": integer
}
400 The body is not a JSON object with an array member asins, or the array holds more than 200 items. A single bad item is not a 400: it is counted in invalid.
{
  "error": string
}
413 The body is over 8 KiB.
{
  "error": string
}
415 The Content-Type is not application/json (a charset parameter is allowed). Answered before the limit, so it spends none of the six.
{
  "error": string
}
429 Past this client's 6 reports a day.
{
  "error": string
}
503 The queue could not store the report. Nothing was recorded.
{
  "error": string
}
POST /hooks/github/release

Release notification (production only)

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

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

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

Parameters

Name In Type Notes
X-Hub-Signature-256 * header string sha256=<hex> HMAC-SHA256 of the raw request body, keyed with the deployment's webhook secret.
X-GitHub-Event header string GitHub's event name. Anything other than release is accepted and ignored.

* required

Request body

{
  "action?": string,
  "repository?": {
    "full_name?": string
  }
}

Responses

202 Accepted. A refresh runs in the background if the payload named a published release of this repository.
400 Unreadable body, or a signed payload that is not valid JSON. Plain text.
401 Missing or invalid X-Hub-Signature-256. Plain text.
413 Body over 1 MiB. Plain text.

Further reading

The full licensing policy is in LICENSING.md. The machine-readable contract for everything on this page is at /api/v1/openapi.json.