Catalog

Rows of media items shown on the home screen and inside the explore section.

A catalog is the simplest way to surface content in wako: a named list of items with a poster, a title, and an ID. Once your manifest declares a catalog, wako fetches it as a row on the home screen and also lets the user open it from Explore for grid browsing.

Declaring a catalog

Catalogs are declared inside the manifest under catalogs:

JSON

{
  "catalogs": [
    {
      "type": "movie",
      "id": "trending",
      "name": "Trending now",
      "extra": [
        { "name": "search" },
        { "name": "skip" },
        {
          "name": "genre",
          "options": ["Action", "Drama", "Comedy", "Documentary"]
        }
      ]
    }
  ]
}

Field	Type	Description
`type` required	`string`	The content kind for this catalog. Most catalogs use `movie` or `series`.
`id` required	`string`	A stable identifier for the catalog. Used by wako in URLs — change it and the user's pinned/hidden state for this row resets.
`name`	`string`	The row title shown on the home screen. Defaults to the `id` if absent.
`extra`	`object[]`	Optional list of parameters the catalog accepts. See below.

Endpoint

HTTP

GET /catalog/{type}/{id}.json
GET /catalog/{type}/{id}/{extra}.json

The first form returns the default contents of the row. The second form is used when wako needs to pass extra parameters (search, pagination, genre…). The {extra} segment is a URL-style query string — each param is key=urlencoded-value, joined by &:

HTTP

GET /catalog/movie/trending/search=blade%20runner.json
GET /catalog/movie/trending/skip=100.json
GET /catalog/movie/trending/genre=Action&skip=20.json

Extras

Extras declare which parameters your catalog accepts. wako only sends the extras you declare.

Field	Type	Description
`search`	`extra`	When declared, the catalog appears as a search target. wako passes the user's query under `search`. The catalog should return results matching the query.
`skip`	`extra`	Enables pagination. wako asks for the next page by sending `skip=<offset>`. Return items starting from that offset — typically pages of 50.
`genre`	`extra (with options[])`	Lets the user filter by genre. Declare the available genres under `options`.

Each extra entry can also be marked isRequired. Required extras prevent wako from showing the catalog on the home screen (since it has no default contents) but the catalog still works from the Explore section, where the user can fill the parameter.

JSON

{
  "name": "search",
  "isRequired": true
}

Response

JSON

{
  "metas": [
    {
      "id": "tt0083658",
      "type": "movie",
      "name": "Blade Runner",
      "poster": "https://example.com/poster.jpg",
      "posterShape": "regular",
      "description": "A blade runner must pursue and terminate four replicants…",
      "releaseInfo": "1982",
      "imdbRating": "8.1",
      "genres": ["Sci-Fi", "Drama"]
    }
  ]
}

Meta preview fields

Each item in metas is a meta preview — a compact subset of the full meta object. The full meta is fetched later, only when the user taps an item.

Field	Type	Description
`id` required	`string`	Stable identifier. Use IMDb IDs (`tt…`) when possible — they let wako join your data with cross-add-on streams, metadata, and watchlist sync. Custom IDs work too, but require your add-on to also serve `meta`.
`type` required	`string`	The content kind (`movie`, `series`…).
`name` required	`string`	Display title.
`poster`	`string (URL)`	Poster image. Keep the source URL small — wako loads many posters in parallel. JPG or WebP under 300 KB renders smoothly.
`posterShape`	`string`	Hint for the aspect ratio. Common values: `regular` (2:3, default for movies/series), `landscape` (16:9), `square`.
`background`	`string (URL)`	Wide hero image used on the detail page.
`logo`	`string (URL)`	Title-treatment logo (transparent PNG) shown over the hero image.
`description`	`string`	Short synopsis. wako truncates this on cards but shows it in full on the detail page.
`releaseInfo`	`string`	Free-form release year string (`2024`, `2018–2022`).
`imdbRating`	`string \| number`	IMDb rating displayed on cards and the detail page.
`genres`	`string[]`	Genre tags. Free-form, displayed as chips.
`links`	`object[]`	External links shown on the detail page. Each link has `name`, `category`, `url`.

Caching

Catalog responses are cached by wako per add-on for a short window — usually a few minutes — so quick navigation around the home screen does not hammer your server. You can also influence caching by returning the optional fields:

Field	Type	Description
`cacheMaxAge`	`number (seconds)`	How long the response can be considered fresh.
`staleRevalidate`	`number (seconds)`	Window during which a stale response can still be shown while wako revalidates in the background.
`staleError`	`number (seconds)`	Window during which a stale response can be served if revalidation fails.

✓

Use IMDb IDs whenever possible

wako joins data across add-ons by IMDb ID. A catalog that returns IMDb IDs gets its items watchlisted, scrobbled, and matched with streams from every other add-on for free. A catalog that returns custom IDs is isolated — users see your row but can't cross-link.

Visibility on the home screen

wako shows every catalog on the home screen by default, except those that require an extra (such as a required search query). Users can manually hide or pin individual catalogs from the add-on detail page — these preferences are per-profile and do not affect what your add-on returns.