**Version: 202601**

# List addable cards

**GET** `/openapi/2026-01/themes/cards`

List all addable cards under the current theme across sources (`theme`, `pb`, `custom`, `extension`, `public`, `gen`), de-duplicated, ordered by source, and paginated.

## Request

**Query Parameters**

- `theme_id` string

  Theme ID. Optional; only used by the `theme` source. Empty -> the theme source returns empty
- `source` string[]

  Data source filter. Multi-value (repeat the param `source=pb&source=public`, or comma-join `source=pb,public`); empty aggregates every source:

  *   `theme`: cards bundled with the theme
  *   `pb`: page-builder cards from public templates
  *   `custom`: page-builder cards from the merchant's custom card templates
  *   `extension`: app extension cards
  *   `public`: public cards
  *   `gen`: AI cards
- `category` string

  Primary category filter. Only applies to the pb source
- `second_category` string

  Secondary category filter. Only applies to the pb source
- `limit` int32

  Page size, defaults to 10, range 1-100
- `page` int32

  Page number
- `template` string

  Template filter. Template name (`index`, `product`, `collection`, `cart`, `page`, `search`, or a custom template name)

## Responses

**200**

OK

**application/json**

**Schema | Example**

**Schema**

- `code` string

  error code
- `message` string

  error message
- `data` object

  - `items` object[]

    Cards on this page

    *   Array \[

    - `id` string

      Global unique ID, shaped by source: pb = `global-<template_id>`; custom = `custom-<template_id>`; theme = the section type; extension / public = the full block type `shoplazza://apps/<app_id>/blocks/<location>/<extension_id>`
    - `source` string

      Source:

      *   `theme`: cards bundled with the theme
      *   `pb`: page-builder cards from public templates
      *   `custom`: page-builder cards from the merchant's custom card templates
      *   `extension`: app extension cards
      *   `public`: public cards
      *   `gen`: AI cards
    - `name` GoogleProtobufValue

      Name. Usually a multi-language object `{"zh-CN": "...", "en-US": "..."}`, but may be a plain string depending on source
    - `category` string

      Primary category (pb only)
    - `second_category` string

      Secondary category (pb only)
    - `description` string

      Description (currently empty for all sources)
    - `preview_image` string

      Preview image URL (pb only)
    - `updated_at` string

      Update time RFC3339 (pb only)
    - `templates` string[]

      Templates the card can be added to. Non-empty = only these template pages; empty = all pages
    - `limit` int32

      Max instances of this card on a single page. 0 = unlimited
    *   \]
  - `total` int32

    Total number of cards across the selected sources
  - `page` int32

    Current page number
  - `limit` int32

    Page size
  - `has_more` boolean

    Whether more pages exist

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "items": [
      {
        "id": "string",
        "source": "string",
        "category": "string",
        "second_category": "string",
        "description": "string",
        "preview_image": "string",
        "updated_at": "string",
        "templates": [
          "string"
        ],
        "limit": 0
      }
    ],
    "total": 0,
    "page": 0,
    "limit": 0,
    "has_more": true
  }
}
```