---
title: "Create Marketplace Listing"
method: POST
path: "/v1/marketplace/listings"
tags: ["Marketplace"]
---

# Create Marketplace Listing

`POST /v1/marketplace/listings`

Create a new marketplace listing for a retriever.

This endpoint allows retriever owners to publish their retrievers to the marketplace
with custom tiers, pricing, and display configuration.

## Request body

- object

## Response `200`

Successful Response

- MarketplaceListing — A marketplace listing for a retriever. This is the unified model for all public and marketplace retrievers. Replaces the PublishedRetriever system with a simpler, more flexible approach. Free tier = public retriever (anyone can subscribe for free) Paid tiers = monetized marketplace offering
  - `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/5307993e44d3/schema)