Skip to main content
PATCH
Publish Marketplace Listing

Authorizations

Authorization
string
header
required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

Path Parameters

listing_id
string
required

Response

Successful Response

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

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

Examples:

"Brand Safety Classification API"

"Video Search Engine"

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.

Required string length: 3 - 50
Examples:

"brand-safety-api"

"video-search"

"product-catalog"

available_tiers
SubscriptionTierConfig · object[]
required

Available subscription tiers (must include at least one tier, typically FREE for public listings)

listing_id
string

Unique identifier for the listing

category
string | null

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.

Example:

"Brand Safety"

groups
string[]

Curated groups this listing belongs to, as lowercase slugs (e.g., 'ip-screening'). Filter the catalog by one with ?group=.

Examples:
tags
string[]

Tags for discovery

logo_url
string | null

URL to listing logo/icon

app_url
string | null

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.

Example:

"https://nga.mxp.co"

icon_base64
string | null

Base64 encoded icon/favicon (data URI format). Max size: ~200KB encoded. Use for small icons.

Maximum string length: 300000
Example:

"data:image/png;base64,iVBORw0KGgoAAAANS..."

display_config
Display Config · object | null

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.

Example:
password_secret_name
string | null

Optional organization secret name containing password for access protection. If set, users must provide password to subscribe (even for free tier).

Example:

"marketplace_password"

status
enum<string>
default:draft

Publication status

Available options:
draft,
published,
archived,
suspended
visibility
enum<string>
default:unlisted

Visibility level. 'listed' = shown in marketplace catalog & homepage showcase. 'unlisted' = accessible via direct link only (not in catalog).

Available options:
listed,
unlisted
is_active
boolean
default:true
deprecated

DEPRECATED: Use 'status' field instead. Computed from status (True if PUBLISHED, False otherwise).

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.

Example:

1

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> | null

When the listing was first published

total_subscribers
integer
default:0

Total number of active subscribers

total_queries
integer
default:0

Total queries executed across all subscribers