Data model samples

Whole responses to copy and change, one for each object the app reads. Every sample on this page is checked against the protocol’s schemas when the site is built. The protocol reference explains each field.

Paths are relative to the add-on’s base URL. IDs in paths are percent-encoded, so example:christmas-carol becomes example%3Achristmas-carol.

Manifest

The smallest useful manifest: one catalog and nothing else. Items in it need IDs that another add-on answers meta and stream for, such as librivox: IDs, as in the seasonal catalogs sample.

GET /manifest.json
{
  "id": "org.example.readings",
  "version": "1.0.0",
  "protocol": 1,
  "name": "Example Readings",
  "description": "",
  "types": [
    "audiobook"
  ],
  "resources": [
    "catalog"
  ],
  "catalogs": [
    {
      "type": "audiobook",
      "id": "christmas",
      "name": "Christmas"
    }
  ]
}

A manifest with every field:

  • meta is narrowed to audiobooks and podcasts: episodes come inside the podcast’s meta.
  • stream answers audiobooks and episodes, and also ol: IDs, so the add-on offers its readings of any Open Library book a listener opens.
  • The search catalog requires search, so it only answers searches and stays off Home.
GET /manifest.json
{
  "id": "org.example.readings",
  "version": "2.1.0",
  "protocol": 1,
  "name": "Example Readings",
  "description": "Public-domain books and a podcast, read by volunteers.",
  "logo": "https://media.example.com/logo.png",
  "types": [
    "audiobook",
    "podcast",
    "episode"
  ],
  "resources": [
    "catalog",
    {
      "name": "meta",
      "types": [
        "audiobook",
        "podcast"
      ]
    },
    {
      "name": "stream",
      "types": [
        "audiobook",
        "episode"
      ],
      "idPrefixes": [
        "example:",
        "ol:"
      ]
    }
  ],
  "idPrefixes": [
    "example:"
  ],
  "catalogs": [
    {
      "type": "audiobook",
      "id": "new",
      "name": "New readings",
      "extra": [
        {
          "name": "genre",
          "options": [
            "children",
            "mystery",
            "poetry"
          ]
        },
        {
          "name": "skip"
        }
      ]
    },
    {
      "type": "audiobook",
      "id": "search",
      "name": "Example Readings",
      "extra": [
        {
          "name": "search",
          "isRequired": true
        },
        {
          "name": "skip"
        }
      ]
    },
    {
      "type": "podcast",
      "id": "shows",
      "name": "Our shows"
    }
  ],
  "configurable": true
}

Catalog response

A list of MetaPreview objects: enough to draw a cover and a title. Only id, type and name are required. Extras arrive in the path, keys sorted. An empty metas list ends paging.

GET /catalog/audiobook/new/genre=children&skip=50.json
{
  "metas": [
    {
      "id": "example:christmas-carol",
      "type": "audiobook",
      "name": "A Christmas Carol",
      "author": "Charles Dickens",
      "cover": "https://archive.org/services/img/A_Christmas_Carol",
      "year": 1843,
      "durationMs": 11669000
    },
    {
      "id": "example:secret-garden",
      "type": "audiobook",
      "name": "The Secret Garden",
      "author": "Frances Hodgson Burnett"
    }
  ],
  "cacheMaxAge": 21600
}

Meta

Everything in the preview, plus the details shown on the book’s page. chapters here apply to a stream that brings none of its own when the stream is as long as the meta’sdurationMs, or to any single-file stream when the meta gives no length.series names the series and the work’s place in it. externalIds tie the item to the same work under another prefix.

GET /meta/audiobook/example%3Achristmas-carol.json
{
  "meta": {
    "id": "example:christmas-carol",
    "type": "audiobook",
    "name": "A Christmas Carol",
    "author": "Charles Dickens",
    "cover": "https://archive.org/services/img/A_Christmas_Carol",
    "description": "Ebenezer Scrooge is visited by three spirits on Christmas Eve.",
    "year": 1843,
    "durationMs": 11669000,
    "narrators": [
      "LibriVox volunteers"
    ],
    "language": "en",
    "genres": [
      "fiction",
      "christmas"
    ],
    "chapters": [
      {
        "title": "Preface and Stave 1",
        "startMs": 0
      },
      {
        "title": "Stave 2",
        "startMs": 2680000
      },
      {
        "title": "Stave 3",
        "startMs": 5340000
      },
      {
        "title": "Stave 4",
        "startMs": 8014000
      },
      {
        "title": "Stave 5",
        "startMs": 10543000
      }
    ],
    "externalIds": {
      "ol": "OL32466W"
    },
    "link": "https://archive.org/details/A_Christmas_Carol"
  },
  "cacheMaxAge": 86400
}

Podcast meta

A podcast with a feed: the app subscribes to the RSS feed and reads new episodes from it directly. Without a feed, list the episodes; each one’s streams are requested with the type episode.

GET /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",
    "description": "What to look for in the sky this month, in fifteen minutes.",
    "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, and what you can see without a telescope."
      }
    ]
  },
  "cacheMaxAge": 3600
}

Stream with parts

A book as several files, played in order. Each part needs a durationMs, from which the app builds one timeline for the whole book, and each part becomes a chapter. These files are a real public-domain LibriVox recording on archive.org.

GET /stream/audiobook/example%3Achristmas-carol.json
{
  "streams": [
    {
      "sourceKey": "christmas-carol-librivox-64kb",
      "name": "Example Readings",
      "title": "LibriVox recording, 64 kbps",
      "mime": "audio/mpeg",
      "bitrate": 64000,
      "downloadable": true,
      "parts": [
        {
          "url": "https://archive.org/download/A_Christmas_Carol/A_Christmas_Carol_Preface_and_Stave_1_Dickens_64kb.mp3",
          "title": "Preface and Stave 1",
          "durationMs": 2680000
        },
        {
          "url": "https://archive.org/download/A_Christmas_Carol/A_Christmas_Carol_Stave_2_Dickens_64kb.mp3",
          "title": "Stave 2",
          "durationMs": 2660000
        },
        {
          "url": "https://archive.org/download/A_Christmas_Carol/A_Christmas_Carol_Stave_3_Dickens_64kb.mp3",
          "title": "Stave 3",
          "durationMs": 2674000
        },
        {
          "url": "https://archive.org/download/A_Christmas_Carol/A_Christmas_Carol_Stave_4_Dickens_64kb.mp3",
          "title": "Stave 4",
          "durationMs": 2529000
        },
        {
          "url": "https://archive.org/download/A_Christmas_Carol/A_Christmas_Carol_Stave_5_Dickens_64kb.mp3",
          "title": "Stave 5",
          "durationMs": 1126000
        }
      ]
    }
  ],
  "cacheMaxAge": 86400
}

Stream with chapters

The same book as one file with chapter marks. A stream has either url or parts, never both. Keep each sourceKey stable: listeners’ saved places depend on it.

GET /stream/audiobook/example%3Achristmas-carol.json
{
  "streams": [
    {
      "sourceKey": "christmas-carol-m4b",
      "name": "Example Readings",
      "title": "One file, with chapters",
      "mime": "audio/mp4",
      "size": 93348000,
      "downloadable": true,
      "url": "https://media.example.com/christmas-carol/christmas-carol.m4b",
      "durationMs": 11669000,
      "chapters": [
        {
          "title": "Preface and Stave 1",
          "startMs": 0
        },
        {
          "title": "Stave 2",
          "startMs": 2680000
        },
        {
          "title": "Stave 3",
          "startMs": 5340000
        },
        {
          "title": "Stave 4",
          "startMs": 8014000
        },
        {
          "title": "Stave 5",
          "startMs": 10543000
        }
      ]
    }
  ],
  "cacheMaxAge": 86400
}

Episode stream

For an episode the add-on listed in a podcast’s episodes. Podcasts with a feed don’t need this: the app plays the enclosures in the feed.

GET /stream/episode/example%3Anight-sky-12.json
{
  "streams": [
    {
      "sourceKey": "night-sky-12",
      "name": "Example Radio",
      "mime": "audio/mpeg",
      "url": "https://media.example.com/night-sky/12.mp3",
      "durationMs": 1684000
    }
  ]
}

Nothing to offer

An add-on that has no stream for an item answers an empty list, not an error. An unknown meta ID answers 404 with { "error": "Not found" }.

GET /stream/audiobook/ol%3AOL69612W.json
{
  "streams": []
}