Skip to main content
PATCH
/
v1
/
marketplace
/
listings
/
{listing_id}
/
publish
Publish Marketplace Listing
curl --request PATCH \
  --url https://api.mixpeek.com/v1/marketplace/listings/{listing_id}/publish
{
  "internal_id": "<string>",
  "namespace_id": "<string>",
  "retriever_id": "<string>",
  "title": "<string>",
  "description": "<string>",
  "public_name": "<string>",
  "available_tiers": [
    {
      "tier": "free",
      "price_per_month": 0,
      "limits": {
        "requests_per_minute": 123,
        "requests_per_hour": 123,
        "requests_per_day": 123,
        "requests_per_month": 123
      },
      "features": [
        "<string>"
      ],
      "stripe_price_id": "<string>"
    }
  ],
  "listing_id": "<string>",
  "category": "<string>",
  "tags": [
    "<string>"
  ],
  "logo_url": "<string>",
  "app_url": "https://nga.mxp.co",
  "icon_base64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "display_config": {
    "components": [
      {
        "props": {
          "field": "video_url",
          "label": "Enter video URL"
        },
        "type": "SearchInput"
      },
      {
        "props": {
          "fields": [
            "title",
            "description",
            "score"
          ],
          "layout": "grid"
        },
        "type": "ResultCard"
      }
    ],
    "theme": {
      "fontFamily": "Inter, sans-serif",
      "primaryColor": "#007AFF"
    }
  },
  "password_secret_name": "marketplace_password",
  "status": "draft",
  "visibility": "unlisted",
  "is_active": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "published_at": "2023-11-07T05:31:56Z",
  "total_subscribers": 0,
  "total_queries": 0
}

Documentation Index

Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Headers

​
Authorization
string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer YOUR_API_KEY"

"Bearer YOUR_STRIPE_API_KEY"

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

Category for browsing (e.g., 'Content Moderation', 'Search')

​
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

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:
{
  "components": [
    {
      "props": {
        "field": "video_url",
        "label": "Enter video URL"
      },
      "type": "SearchInput"
    },
    {
      "props": {
        "fields": ["title", "description", "score"],
        "layout": "grid"
      },
      "type": "ResultCard"
    }
  ],
  "theme": {
    "fontFamily": "Inter, sans-serif",
    "primaryColor": "#007AFF"
  }
}
​
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).

​
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