---
title: "Update Marketplace Listing"
method: PATCH
path: "/v1/marketplace/listings/{listing_id}"
tags: ["Marketplace"]
---

# Update Marketplace Listing

`PATCH /v1/marketplace/listings/{listing_id}`

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/marketplace/listings/{listing_id}`
- Auth: HTTP bearer

Update an existing marketplace listing.

## Path parameters

- `listing_id` string, required

## 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: Catalog category. One of: Brand Safety, Advertising, Media, Faces & People, Art & Archives, Personalization, Content Safety, Spatial, Ecommerce. Writes also accept the slug form (e.g., 'faces-and-people') and store the label.
  - `groups` string[]: Curated groups this listing belongs to, as lowercase slugs (e.g., 'ip-screening'). Filter the catalog by one with ?group=.
  - `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`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-17** `24540a9a39c0`: 1 info
  - added the optional property `groups` to the response with the `200` status
- **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - added the optional property `success` to the response with the `422` status
  - …2 more
- **2026-08-09** `5d4c905106b4`: 1 info
  - the endpoint scheme security `BearerAuth` was added to the API
- **2026-07-26** `7cb051533311`: 1 info
  - added the optional property `featured_rank` to the response with the `200` status

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/marketplace/listings/:listing_id/patch.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)