Protocol v1

The reference for what an add-on answers. The SDK implements all of it; you only need this page to check a detail or to write an add-on in another language. For whole objects to copy, see the data model samples.

Routes

All paths are relative to the add-on’s base URL: the manifest URL without manifest.json. An add-on can live under a path, such as https://catalog.lelap.app/librivox/manifest.json.

GET /manifest.json                          → Manifest
GET /catalog/{type}/{id}.json               → { "metas": MetaPreview[] }
GET /catalog/{type}/{id}/{extra}.json       → { "metas": MetaPreview[] }
GET /meta/{type}/{id}.json                  → { "meta": Meta }
GET /stream/{type}/{id}.json                → { "streams": Stream[] }
POST /scrobble                              ← { "events": ScrobbleEvent[] }
  • {type} is a content type: audiobook, podcast or episode.
  • {id} is percent-encoded with encodeURIComponent, so example:secret-garden arrives as example%3Asecret-garden and a / in an ID as %2F. Split the path on / first, then decode each segment.
  • {extra} is a query string in a path segment, such as genre=children&skip=20. The app sorts the keys alphabetically, leaves out empty values and encodes keys and values with encodeURIComponent, so the same request always has the same URL and caches well. Decode + as a space, as in a query string. Without extras the path is /catalog/{type}/{id}.json.
Examples
https://addon.example.com/catalog/audiobook/new/genre=children&skip=20.json
https://addon.example.com/catalog/audiobook/search/search=secret%20garden.json
https://addon.example.com/meta/audiobook/example%3Asecret-garden.json
https://addon.example.com/stream/audiobook/example%3Asecret-garden.json

HTTP

  • Answer GET (and HEAD). Answer OPTIONS preflights with 204 and the CORS headers.
  • Send Access-Control-Allow-Origin: * on every response, errors included. The web app calls add-ons straight from the browser.
  • Respond with Content-Type: application/json; charset=utf-8.
  • Serve over HTTPS: the web app can’t reach plain HTTP from an HTTPS page.
  • Answer within 10 seconds. The app gives up on slower answers and shows what other add-ons returned.
  • Catalog, meta and stream responses may carry cacheMaxAge: how many seconds the response may be kept. Send the same value as Cache-Control: public, max-age=…so HTTP caches agree; the SDK does both, and gives the manifest an hour.
  • Times and lengths are integer milliseconds (durationMs, startMs), sizes are bytes, released is ISO 8601 and cacheMaxAge is seconds.
  • Use only the fields on this page. The app drops fields it doesn’t know, and the JSON Schema rejects them.
Response headers
Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: *
Cache-Control: public, max-age=21600

IDs and routing

Every item has an ID of the form prefix:value. The prefix starts with a lowercase letter and has only lowercase letters, digits, _ and -; the value is anything that isn’t empty. The whole ID is 3 to 512 characters.

PrefixValueExample
ol:An Open Library work ID. Canonical for books.ol:OL69612W
librivox:The archive.org identifier of a LibriVox recording.librivox:secret_garden_librivox
asin:An Audible ASIN. The Catalog add-on answers its meta from Audnexus.asin:B002UZMLXM
podcast:A podcast’s GUID.podcast:917393e3-1b1e-5cef-ace4-edaa54e1f810

Use an ol: ID for a book when you know it, or name it in externalIds. An asin in externalIds ties a book to its Audible recording, whose narrators, series and chapters the Catalog add-on reads from Audnexus. For your own items, pick a prefix of your own.

The app decides whom to ask for an item’s meta and stream:

  1. The add-on must list the resource in resources, and the item’s type in that resource’s types (or, without them, in the manifest’s types).
  2. The ID must start with one of the resource’s idPrefixes. A resource object’s idPrefixes replace the manifest’s; without either, the add-on is asked for any ID. Include the colon (ol:, not ol), since the app compares the start of the ID.
  3. meta comes from the first matching add-on, in the order the listener keeps them. stream is asked of every matching add-on, and the answers are merged in that order.

In the example manifest below, meta is only asked for example: IDs, but stream also for ol: IDs: the add-on offers its recordings for any Open Library book the listener opens, whichever add-on listed it.

Manifest

GET /manifest.json answers with the manifest itself.

FieldTypeRequiredMeaning
idstringyesReverse DNS, such as org.example.myaddon; at least 3 characters. Keep it stable.
versionstringyesYour add-on’s semantic version, such as 1.2.0.
protocol1yesThe protocol version. Always 1 for this reference.
namestringyesShown to listeners. Not empty.
descriptionstringyesA sentence about what the add-on serves. May be empty.
logoURLnoAn http or https image URL.
typesContentType[]yesThe types you serve: audiobook, podcast, episode. At least one.
resources(ResourceName | Resource)[]yesWhat you answer: catalog, meta, stream, scrobble, each as a name or as a Resource object. At least one.
idPrefixesstring[]noPrefixes of the IDs you answer meta and stream for, such as example:. Without it, any ID.
catalogsCatalogDefinition[]yesYour catalogs. Use [] when you have none.
configurablebooleannotrue when the add-on has a /configure page.

Resource

A resources entry is a name ("catalog", "meta", "stream", "scrobble") or an object:

FieldTypeRequiredMeaning
name"catalog" | "meta" | "stream" | "scrobble"yesThe resource.
typesContentType[]noThe types this resource answers, if fewer than the manifest’s types.
idPrefixesstring[]noReplaces the manifest’s idPrefixes for this resource.
GET /manifest.json
{
  "id": "com.example.readings",
  "version": "1.0.0",
  "protocol": 1,
  "name": "Example Readings",
  "description": "Public-domain books read by volunteers.",
  "logo": "https://addon.example.com/logo.png",
  "types": [
    "audiobook"
  ],
  "resources": [
    "catalog",
    "meta",
    {
      "name": "stream",
      "idPrefixes": [
        "example:",
        "ol:"
      ]
    }
  ],
  "idPrefixes": [
    "example:"
  ],
  "catalogs": [
    {
      "type": "audiobook",
      "id": "new",
      "name": "New releases",
      "extra": [
        {
          "name": "genre",
          "options": [
            "children",
            "mystery",
            "poetry"
          ]
        },
        {
          "name": "skip"
        }
      ]
    },
    {
      "type": "audiobook",
      "id": "search",
      "name": "Example Readings",
      "extra": [
        {
          "name": "search",
          "isRequired": true
        },
        {
          "name": "skip"
        }
      ]
    }
  ]
}

Catalogs

A catalog is a list of items to browse or search. It answers with { "metas": MetaPreview[], "cacheMaxAge"?: number }. Only catalogs declared in the manifest are requested.

CatalogDefinition

FieldTypeRequiredMeaning
typeContentTypeyesThe type of every item in it.
idstringyesUnique among your catalogs of this type; part of the URL. Not empty.
namestringyesShown as the heading of the row or list. Not empty.
extraCatalogExtra[]noThe extras this catalog accepts.
shelfstringnoWhat the list is to the listener. want-to-read puts it on Home as **Want to read**, first after Continue listening. Other values are ignored.

CatalogExtra

FieldTypeRequiredMeaning
namestringyessearch, genre or skip. The app ignores other names.
isRequiredbooleannoThe catalog only answers with this extra set.
optionsstring[]noThe allowed values, for genre.

The extras the app understands:

  • search: what the listener typed. A catalog with a search extra can be searched; when it’s required, the catalog only answers searches and stays off Home.
  • genre: one of the options, shown as filters.
  • skip: how many items to skip, as a decimal string, for the next page. Return an empty metas list when there are no more.

Catalogs without a required extra can appear on Home.

MetaPreview

One item in a catalog: enough to draw a cover and a title.

FieldTypeRequiredMeaning
idIDyesThe item’s ID, prefix:value.
typeContentTypeyesThe item’s type.
namestringyesThe title. Not empty.
authorstringnoAuthor, or a podcast’s publisher.
coverURLnoCover image, http or https.
descriptionstringnoPlain text.
yearintegernoYear of first publication.
durationMsinteger ≥ 0noTotal length in milliseconds.
GET https://addon.example.com/catalog/audiobook/new/genre=children&skip=20.json
{
  "metas": [
    {
      "id": "example:secret-garden",
      "type": "audiobook",
      "name": "The Secret Garden",
      "author": "Frances Hodgson Burnett",
      "cover": "https://media.example.com/secret-garden/cover.jpg",
      "year": 1911,
      "durationMs": 27812000
    },
    {
      "id": "example:wind-in-the-willows",
      "type": "audiobook",
      "name": "The Wind in the Willows",
      "author": "Kenneth Grahame",
      "cover": "https://media.example.com/wind-in-the-willows/cover.jpg",
      "year": 1908
    }
  ],
  "cacheMaxAge": 21600
}

Meta

GET /meta/{type}/{id}.json answers with { "meta": Meta, "cacheMaxAge"?: number }, or a 404 when the ID is unknown. Meta has every MetaPreview field, plus:

FieldTypeRequiredMeaning
narratorsstring[]noWho reads it.
seriesSeries[]noSeries the work belongs to, main series first.
languagestringnoBCP 47 or ISO 639 code, such as en or pt-BR.
genresstring[]noFree-form genres or subjects.
chaptersChapter[]noChapters across the whole item. The app uses them for a stream without chapters of its own when the stream is as long as durationMs (within 15 seconds); without a durationMs they apply to any single-file stream.
externalIdsobject<string, string>noThe same work under other prefixes: prefix without the colon to value, such as { "ol": "OL69612W" }.
episodesEpisode[]noFor podcasts, the episodes.
linkURLnoA page about the item on the source’s own site.
feedURLnoFor podcasts, the RSS feed. The app subscribes to it and reads it directly.

Chapter

FieldTypeRequiredMeaning
titlestringyesThe chapter title. May be empty.
startMsinteger ≥ 0yesWhere it starts, in milliseconds from the beginning of the audio.

Series

FieldTypeRequiredMeaning
namestringyesThe series name.
positionstringnoWhere the work sits in it, as a label such as 1 or 2.5.

Episode

FieldTypeRequiredMeaning
idIDyesThe episode’s ID; its streams are requested with type episode.
titlestringyesThe episode title.
releasedstringnoISO 8601 date and time, such as 2026-11-02T06:00:00Z.
durationMsinteger ≥ 0noLength in milliseconds.
descriptionstringnoShow notes, plain text.
GET https://addon.example.com/meta/audiobook/example%3Asecret-garden.json
{
  "meta": {
    "id": "example:secret-garden",
    "type": "audiobook",
    "name": "The Secret Garden",
    "author": "Frances Hodgson Burnett",
    "cover": "https://media.example.com/secret-garden/cover.jpg",
    "description": "An orphan finds a locked garden and brings it back to life.",
    "year": 1911,
    "durationMs": 27812000,
    "narrators": [
      "Ana Reader"
    ],
    "series": [
      {
        "name": "Garden Stories",
        "position": "1"
      }
    ],
    "language": "en",
    "genres": [
      "children",
      "fiction"
    ],
    "chapters": [
      {
        "title": "There Is No One Left",
        "startMs": 0
      },
      {
        "title": "Mistress Mary Quite Contrary",
        "startMs": 1123000
      }
    ],
    "externalIds": {
      "ol": "OL69612W"
    },
    "link": "https://example.com/books/secret-garden"
  },
  "cacheMaxAge": 86400
}
GET https://addon.example.com/meta/podcast/example%3Anight-sky.json
{
  "meta": {
    "id": "example:night-sky",
    "type": "podcast",
    "name": "Night Sky Notes",
    "author": "Example Radio",
    "cover": "https://media.example.com/night-sky/cover.jpg",
    "language": "en",
    "feed": "https://media.example.com/night-sky/feed.xml",
    "episodes": [
      {
        "id": "example:night-sky-12",
        "title": "Finding the Pleiades",
        "released": "2026-11-02T06:00:00Z",
        "durationMs": 1684000,
        "description": "Where to look this month, and what you can see without a telescope."
      }
    ]
  }
}

Streams

GET /stream/{type}/{id}.json answers with { "streams": Stream[], "cacheMaxAge"?: number }. Each stream is one way to play the item, such as one reading of a book. With nothing to offer, answer { "streams": [] }.

A stream is either a single file, with url, or a list of files, with parts; never both. Both kinds have these fields:

FieldTypeRequiredMeaning
sourceKeystringyesStable for this source and item, 1 to 256 characters. The app keys saved places on it, so never reuse or change it.
namestringyesWho provides it, such as your add-on’s name. Not empty.
titlestringnoWhat sets it apart from other streams, such as the reader.
mimestringnoSuch as audio/mpeg.
bitrateinteger > 0noBits per second, such as 64000.
sizeinteger ≥ 0noTotal size in bytes.
downloadablebooleannoThe source allows keeping a copy for offline listening.

Single file

FieldTypeRequiredMeaning
urlURLyesThe audio file, http or https.
durationMsinteger ≥ 0noLength in milliseconds.
chaptersChapter[]noChapters within the file.

Parts

FieldTypeRequiredMeaning
partsStreamPart[]yesThe files in playing order. At least one.

StreamPart

FieldTypeRequiredMeaning
urlURLyesThe audio file, http or https.
titlestringnoShown as the chapter; without it the app shows “Part 1”, “Part 2” and so on.
durationMsinteger ≥ 0yesLength in milliseconds. The app builds the book’s timeline from it.
sizeinteger ≥ 0noSize in bytes.

With parts, each part becomes a chapter. A single file uses its own chapters, or the meta’s.

GET https://addon.example.com/stream/audiobook/example%3Asecret-garden.json
{
  "streams": [
    {
      "sourceKey": "secret-garden-ana",
      "name": "Example Readings",
      "title": "Read by Ana Reader",
      "mime": "audio/mpeg",
      "bitrate": 64000,
      "downloadable": true,
      "parts": [
        {
          "url": "https://media.example.com/secret-garden/01.mp3",
          "title": "There Is No One Left",
          "durationMs": 1123000,
          "size": 8984000
        },
        {
          "url": "https://media.example.com/secret-garden/02.mp3",
          "title": "Mistress Mary Quite Contrary",
          "durationMs": 1342000,
          "size": 10736000
        }
      ]
    },
    {
      "sourceKey": "secret-garden-ben-m4b",
      "name": "Example Readings",
      "title": "Read by Ben Narrator, one file",
      "mime": "audio/mp4",
      "size": 222496000,
      "url": "https://media.example.com/secret-garden/full.m4b",
      "durationMs": 27812000,
      "chapters": [
        {
          "title": "There Is No One Left",
          "startMs": 0
        },
        {
          "title": "Mistress Mary Quite Contrary",
          "startMs": 1123000
        }
      ]
    }
  ],
  "cacheMaxAge": 86400
}

Links that expire

If your source hands out audio URLs that stop working after a while, give the stream or part a stable url on your add-on instead, such as /resolve/…, and answer it with a 302 redirect to a fresh audio URL and Cache-Control: no-store. When the audio host later answers 403 or 410, the player and the downloader request your url again, once per expiry, and continue at the same place. The web player can’t see the status of a failed audio request, so it does this after any network error. The audio still goes straight from the source to the listener.

Errors

Answer errors with a non-2xx status and { "error": string }: 404for an unknown route, catalog or ID, 400 for extras you can’t use, 5xxwhen something upstream failed. The app treats a failing add-on as having nothing right now and keeps the answers of the others.

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *

{ "error": "Not found" }

Scrobble

An add-on with scrobble in resources hears what the listener plays, for example to keep a reading tracker or another podcast app up to date. The app sends POST /scrobble with a JSON body of up to 100 events, oldest first, to every installed add-on that declares it for the item’s type. A Resource object’s idPrefixes narrow it to those IDs; the manifest’s own prefixes don’t apply here.

  • start when playing starts, progress about every five minutes while it plays, pause when it stops or another item takes over, and finish at the end. abandon (the listener gave up) and rate are part of the protocol; the app doesn’t send them yet.
  • Events wait on the device and go out when the add-on can be reached, so a train ride offline is reported afterwards, with each event’s own at.
  • Events never carry a source, stream or file URL. Episodes carry their feed and guid; read the public feed if you need more.
  • Answer 2xx when the events are handled or deliberately ignored. A 4xx (other than 408 and 429) drops them; anything else, or no answer, makes the app try again later, waiting longer each time, for up to 30 days. Keep handling idempotent: set states rather than adding to them.

ScrobbleEvent

FieldTypeRequiredMeaning
eventIdstringyes8 to 128 characters, unique per event. The app sends an event again when it did not get an answer, so ignore an ID you have handled.
eventstringyesstart, progress, pause, finish, abandon or rate.
atinteger ≥ 0yesWhen it happened, as Unix time in milliseconds. Listening offline arrives later with its own times.
itemScrobbleItemyesWhat was played.
positionMsinteger ≥ 0noWhere the listener was on the whole item’s timeline.
sessionStartMsinteger ≥ 0noFor progress, pause and finish: where this listening session started.
ratingnumbernoFor rate: 0.5 to 5 stars, in steps of 0.5.

ScrobbleItem

FieldTypeRequiredMeaning
typeContentTypeyesThe item’s type.
idstringnoThe item’s ID. Missing for the listener’s own files.
externalIdsobjectnoThe same work under other prefixes, such as { "isbn": "9780141036144" }.
namestringyesThe title. Not empty.
authorstringnoThe author.
durationMsinteger ≥ 0noThe whole item’s length.
podcastobjectnoFor episodes: feed (the RSS feed URL), guid and title of the podcast.
episodeGuidstringnoFor episodes: the item’s guid in the feed, or its enclosure URL when the feed gives none.
POST /scrobble
{
  "events": [
    {
      "eventId": "0196f2a4-5c1e-7a3b-9d4e-2f6a8b1c3d5e",
      "event": "pause",
      "at": 1763370000000,
      "item": {
        "type": "audiobook",
        "id": "ol:OL69612W",
        "externalIds": {
          "isbn": "9780141036144"
        },
        "name": "Walden",
        "author": "Henry David Thoreau",
        "durationMs": 41520000
      },
      "positionMs": 3725000,
      "sessionStartMs": 2100000
    },
    {
      "eventId": "0196f2a4-61aa-7c40-8e11-4b7d9e0f1a2c",
      "event": "finish",
      "at": 1763380000000,
      "item": {
        "type": "episode",
        "name": "Episode 12",
        "durationMs": 1800000,
        "podcast": {
          "feed": "https://feeds.example.org/show.xml",
          "title": "Example Show"
        },
        "episodeGuid": "ep-12"
      },
      "positionMs": 1800000
    }
  ]
}

The SDK validates the body and calls your scrobble handler with the events. See Scrobbling for the first-party Hardcover and gPodder add-ons.

Configuration page

With "configurable": true, the app links to /configure under the add-on’s base URL and opens it in the browser. It’s a normal web page; v1 has no API between it and the app.

The app only remembers the manifest URL, and add-ons are stateless, so put the settings in the URL. For example, a page that picks a language can hand out https://addon.example.com/lang=de/manifest.json for the listener to add in place of the plain one, and serve every route under /lang=de/. Never put passwords or tokens in those URLs in plain text: seal them with a key only your add-on has (for example AES-GCM), and don’t store or log them. The first-party scrobble add-ons do this. The app keeps manifest URLs on the device and syncs them end-to-end encrypted.

JSON Schema

/docs/protocol.schema.json is a JSON Schema (draft 2020-12) generated from the SDK’s schemas, with Manifest, CatalogResponse, MetaResponse, StreamResponse and ScrobbleRequest under $defs. Point a validator or your editor at one of them:

{ "$ref": "https://lelap.app/docs/protocol.schema.json#/$defs/Manifest" }