---
title: "Browse Marketplace Catalog"
method: GET
path: "/v1/marketplace/catalog"
tags: ["Marketplace"]
---

# Browse Marketplace Catalog

`GET /v1/marketplace/catalog`

Browse marketplace catalog with optional filters.

Returns published, listed marketplace listings only. Unlisted retrievers
are still accessible via direct link but don't appear here.

## Query parameters

- `category` string, nullable — Filter by category (e.g., 'Content Moderation', 'Search')
- `tags` string[], nullable — Filter by tags (AND logic - listing must have all tags)
- `search` string, nullable — Search in title and description
- `skip` integer — Number of listings to skip
- `limit` integer — Number of listings to return

## Response `200`

Successful Response

- MarketplaceListing[]
  - `listing_id` string — Unique identifier for the listing
  - `internal_id` string, required — Organization that owns this listing (provider)
  - `namespace_id` string, required — Namespace containing the retriever
  - `retriever_id` string, required — Retriever being offered in the marketplace
  - `title` string, required — Public display title
  - `description` string, required — Public description of what this listing provides
  - `public_name` string, required — Public URL-safe slug for the listing (e.g., 'video-search'). Used in public URL: mxp.co/m/{public_name}. Must be globally unique.
  - `category` string, nullable — Category for browsing (e.g., 'Content Moderation', 'Search')
  - `tags` string[] — Tags for discovery
  - `logo_url` string, nullable — URL to listing logo/icon
  - `app_url` string, nullable — Optional URL to a live canvas app powered by this retriever (e.g., 'https://nga.mxp.co'). When set, the listing appears in the public showcase at mixpeek.com/showcase.
  - `icon_base64` string, nullable — Base64 encoded icon/favicon (data URI format). Max size: ~200KB encoded. Use for small icons.
  - `available_tiers` SubscriptionTierConfig[], required — Available subscription tiers (must include at least one tier, typically FREE for public listings)
    - `tier` 'free' | 'basic' | 'pro' | 'enterprise', required — Subscription tier levels for marketplace offerings.
    - `price_per_month` number — Monthly price in USD (0.0 for free tier)
    - `limits` TierLimits — Rate limits and quotas for a subscription tier.
      - `requests_per_minute` integer, nullable — Maximum requests per minute (None = unlimited)
      - `requests_per_hour` integer, nullable — Maximum requests per hour (None = unlimited)
      - `requests_per_day` integer, nullable — Maximum requests per day (None = unlimited)
      - `requests_per_month` integer, nullable — Maximum requests per month (None = unlimited)
    - `features` string[] — List of features included in this tier
    - `stripe_price_id` string, nullable — Stripe price ID for paid tiers
  - `display_config` object, nullable — JSON-based UI configuration for the public interface. Follows a component-based schema (inspired by json-render): { 'components': [...], 'theme': {...}, 'layout': {...} }. If not provided, a default UI is generated from retriever input_schema.
  - `password_secret_name` string, nullable — Optional organization secret name containing password for access protection. If set, users must provide password to subscribe (even for free tier).
  - `status` 'draft' | 'published' | 'archived' | 'suspended' — Status of a marketplace listing.
  - `visibility` 'listed' | 'unlisted' — Visibility level for a marketplace listing. - LISTED: Appears in marketplace catalog, homepage showcase, and sitemap. - UNLISTED: Accessible via direct link but hidden from catalog/showcase.
  - `is_active` boolean — DEPRECATED: Use 'status' field instead. Computed from status (True if PUBLISHED, False otherwise).
  - `featured_rank` integer, nullable — Editorial ordering for the catalog. Lower sorts first (1 = top slot). Listings without a rank fall back to subscriber-count ordering and always sort after ranked ones. This is the single source of truth for catalog order — the homepage showcase, the homepage landing-page showcase strip, and the Studio marketplace all read it, so ordering never has to be hardcoded per-surface.
  - `created_at` string, date-time — When the listing was created
  - `updated_at` string, date-time — When the listing was last updated
  - `published_at` string, date-time, nullable — When the listing was first published
  - `total_subscribers` integer — Total number of active subscribers
  - `total_queries` integer — Total queries executed across all subscribers

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/c768d4d28e4c/schema)