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,podcastorepisode.{id}is percent-encoded withencodeURIComponent, soexample:secret-gardenarrives asexample%3Asecret-gardenand 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 asgenre=children&skip=20. The app sorts the keys alphabetically, leaves out empty values and encodes keys and values withencodeURIComponent, 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.
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.jsonHTTP
- Answer
GET(andHEAD). AnswerOPTIONSpreflights with204and 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 asCache-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,releasedis ISO 8601 andcacheMaxAgeis seconds. - Use only the fields on this page. The app drops fields it doesn’t know, and the JSON Schema rejects them.
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=21600IDs 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.
| Prefix | Value | Example |
|---|---|---|
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:
- The add-on must list the resource in
resources, and the item’s type in that resource’stypes(or, without them, in the manifest’stypes). - The ID must start with one of the resource’s
idPrefixes. A resource object’sidPrefixesreplace the manifest’s; without either, the add-on is asked for any ID. Include the colon (ol:, notol), since the app compares the start of the ID. metacomes from the first matching add-on, in the order the listener keeps them.streamis 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.
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string | yes | Reverse DNS, such as org.example.myaddon; at least 3 characters. Keep it stable. |
version | string | yes | Your add-on’s semantic version, such as 1.2.0. |
protocol | 1 | yes | The protocol version. Always 1 for this reference. |
name | string | yes | Shown to listeners. Not empty. |
description | string | yes | A sentence about what the add-on serves. May be empty. |
logo | URL | no | An http or https image URL. |
types | ContentType[] | yes | The types you serve: audiobook, podcast, episode. At least one. |
resources | (ResourceName | Resource)[] | yes | What you answer: catalog, meta, stream, scrobble, each as a name or as a Resource object. At least one. |
idPrefixes | string[] | no | Prefixes of the IDs you answer meta and stream for, such as example:. Without it, any ID. |
catalogs | CatalogDefinition[] | yes | Your catalogs. Use [] when you have none. |
configurable | boolean | no | true when the add-on has a /configure page. |
Resource
A resources entry is a name ("catalog", "meta", "stream", "scrobble") or an object:
| Field | Type | Required | Meaning |
|---|---|---|---|
name | "catalog" | "meta" | "stream" | "scrobble" | yes | The resource. |
types | ContentType[] | no | The types this resource answers, if fewer than the manifest’s types. |
idPrefixes | string[] | no | Replaces the manifest’s idPrefixes for this resource. |
{
"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
| Field | Type | Required | Meaning |
|---|---|---|---|
type | ContentType | yes | The type of every item in it. |
id | string | yes | Unique among your catalogs of this type; part of the URL. Not empty. |
name | string | yes | Shown as the heading of the row or list. Not empty. |
extra | CatalogExtra[] | no | The extras this catalog accepts. |
shelf | string | no | What 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
| Field | Type | Required | Meaning |
|---|---|---|---|
name | string | yes | search, genre or skip. The app ignores other names. |
isRequired | boolean | no | The catalog only answers with this extra set. |
options | string[] | no | The allowed values, for genre. |
The extras the app understands:
search: what the listener typed. A catalog with asearchextra can be searched; when it’s required, the catalog only answers searches and stays off Home.genre: one of theoptions, shown as filters.skip: how many items to skip, as a decimal string, for the next page. Return an emptymetaslist 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.
| Field | Type | Required | Meaning |
|---|---|---|---|
id | ID | yes | The item’s ID, prefix:value. |
type | ContentType | yes | The item’s type. |
name | string | yes | The title. Not empty. |
author | string | no | Author, or a podcast’s publisher. |
cover | URL | no | Cover image, http or https. |
description | string | no | Plain text. |
year | integer | no | Year of first publication. |
durationMs | integer ≥ 0 | no | Total length in milliseconds. |
{
"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:
| Field | Type | Required | Meaning |
|---|---|---|---|
narrators | string[] | no | Who reads it. |
series | Series[] | no | Series the work belongs to, main series first. |
language | string | no | BCP 47 or ISO 639 code, such as en or pt-BR. |
genres | string[] | no | Free-form genres or subjects. |
chapters | Chapter[] | no | Chapters 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. |
externalIds | object<string, string> | no | The same work under other prefixes: prefix without the colon to value, such as { "ol": "OL69612W" }. |
episodes | Episode[] | no | For podcasts, the episodes. |
link | URL | no | A page about the item on the source’s own site. |
feed | URL | no | For podcasts, the RSS feed. The app subscribes to it and reads it directly. |
Chapter
| Field | Type | Required | Meaning |
|---|---|---|---|
title | string | yes | The chapter title. May be empty. |
startMs | integer ≥ 0 | yes | Where it starts, in milliseconds from the beginning of the audio. |
Series
| Field | Type | Required | Meaning |
|---|---|---|---|
name | string | yes | The series name. |
position | string | no | Where the work sits in it, as a label such as 1 or 2.5. |
Episode
| Field | Type | Required | Meaning |
|---|---|---|---|
id | ID | yes | The episode’s ID; its streams are requested with type episode. |
title | string | yes | The episode title. |
released | string | no | ISO 8601 date and time, such as 2026-11-02T06:00:00Z. |
durationMs | integer ≥ 0 | no | Length in milliseconds. |
description | string | no | Show notes, plain text. |
{
"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
}{
"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:
| Field | Type | Required | Meaning |
|---|---|---|---|
sourceKey | string | yes | Stable for this source and item, 1 to 256 characters. The app keys saved places on it, so never reuse or change it. |
name | string | yes | Who provides it, such as your add-on’s name. Not empty. |
title | string | no | What sets it apart from other streams, such as the reader. |
mime | string | no | Such as audio/mpeg. |
bitrate | integer > 0 | no | Bits per second, such as 64000. |
size | integer ≥ 0 | no | Total size in bytes. |
downloadable | boolean | no | The source allows keeping a copy for offline listening. |
Single file
| Field | Type | Required | Meaning |
|---|---|---|---|
url | URL | yes | The audio file, http or https. |
durationMs | integer ≥ 0 | no | Length in milliseconds. |
chapters | Chapter[] | no | Chapters within the file. |
Parts
| Field | Type | Required | Meaning |
|---|---|---|---|
parts | StreamPart[] | yes | The files in playing order. At least one. |
StreamPart
| Field | Type | Required | Meaning |
|---|---|---|---|
url | URL | yes | The audio file, http or https. |
title | string | no | Shown as the chapter; without it the app shows “Part 1”, “Part 2” and so on. |
durationMs | integer ≥ 0 | yes | Length in milliseconds. The app builds the book’s timeline from it. |
size | integer ≥ 0 | no | Size in bytes. |
With parts, each part becomes a chapter. A single file uses its own chapters, or the meta’s.
{
"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.
startwhen playing starts,progressabout every five minutes while it plays,pausewhen it stops or another item takes over, andfinishat the end.abandon(the listener gave up) andrateare 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
2xxwhen the events are handled or deliberately ignored. A4xx(other than408and429) 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
| Field | Type | Required | Meaning |
|---|---|---|---|
eventId | string | yes | 8 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. |
event | string | yes | start, progress, pause, finish, abandon or rate. |
at | integer ≥ 0 | yes | When it happened, as Unix time in milliseconds. Listening offline arrives later with its own times. |
item | ScrobbleItem | yes | What was played. |
positionMs | integer ≥ 0 | no | Where the listener was on the whole item’s timeline. |
sessionStartMs | integer ≥ 0 | no | For progress, pause and finish: where this listening session started. |
rating | number | no | For rate: 0.5 to 5 stars, in steps of 0.5. |
ScrobbleItem
| Field | Type | Required | Meaning |
|---|---|---|---|
type | ContentType | yes | The item’s type. |
id | string | no | The item’s ID. Missing for the listener’s own files. |
externalIds | object | no | The same work under other prefixes, such as { "isbn": "9780141036144" }. |
name | string | yes | The title. Not empty. |
author | string | no | The author. |
durationMs | integer ≥ 0 | no | The whole item’s length. |
podcast | object | no | For episodes: feed (the RSS feed URL), guid and title of the podcast. |
episodeGuid | string | no | For episodes: the item’s guid in the feed, or its enclosure URL when the feed gives none. |
{
"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" }