> ## 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. # Create Marketplace Listing > 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. ## OpenAPI ````yaml post /v1/marketplace/listings openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: - BearerAuth: [] paths: /v1/marketplace/listings: post: tags: - Marketplace summary: Create Marketplace Listing description: >- 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. operationId: create_marketplace_listing_v1_marketplace_listings_post parameters: [] requestBody: required: true content: application/json: schema: type: object additionalProperties: true title: Listing Data description: >- Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02). x-unknown-keys: until: '2026-11-02' then: 422 extra_forbidden responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MarketplaceListing' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: MarketplaceListing: properties: listing_id: type: string title: Listing Id description: Unique identifier for the listing internal_id: type: string title: Internal Id description: Organization that owns this listing (provider) namespace_id: type: string title: Namespace Id description: Namespace containing the retriever retriever_id: type: string title: Retriever Id description: Retriever being offered in the marketplace title: type: string title: Title description: Public display title examples: - Brand Safety Classification API - Video Search Engine description: type: string title: Description description: Public description of what this listing provides public_name: type: string maxLength: 50 minLength: 3 title: Public Name description: >- Public URL-safe slug for the listing (e.g., 'video-search'). Used in public URL: mxp.co/m/{public_name}. Must be globally unique. examples: - brand-safety-api - video-search - product-catalog category: anyOf: - type: string - type: 'null' title: Category description: >- 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. examples: - Brand Safety - Media groups: items: type: string type: array title: Groups description: >- Curated groups this listing belongs to, as lowercase slugs (e.g., 'ip-screening'). Filter the catalog by one with ?group=. examples: - - ip-screening - - media-archives tags: items: type: string type: array title: Tags description: Tags for discovery logo_url: anyOf: - type: string - type: 'null' title: Logo Url description: URL to listing logo/icon app_url: anyOf: - type: string - type: 'null' title: App Url description: >- 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. examples: - https://nga.mxp.co - https://mxp.co/r/superbowl icon_base64: anyOf: - type: string maxLength: 300000 - type: 'null' title: Icon Base64 description: >- Base64 encoded icon/favicon (data URI format). Max size: ~200KB encoded. Use for small icons. examples: - data:image/png;base64,iVBORw0KGgoAAAANS... available_tiers: items: $ref: '#/components/schemas/SubscriptionTierConfig' type: array title: Available Tiers description: >- Available subscription tiers (must include at least one tier, typically FREE for public listings) display_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Display Config description: >- 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. examples: - 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: anyOf: - type: string - type: 'null' title: Password Secret Name description: >- Optional organization secret name containing password for access protection. If set, users must provide password to subscribe (even for free tier). examples: - marketplace_password - demo_access_password status: $ref: '#/components/schemas/ListingStatus' description: Publication status default: draft visibility: $ref: '#/components/schemas/ListingVisibility' description: >- Visibility level. 'listed' = shown in marketplace catalog & homepage showcase. 'unlisted' = accessible via direct link only (not in catalog). default: unlisted is_active: type: boolean title: Is Active description: >- DEPRECATED: Use 'status' field instead. Computed from status (True if PUBLISHED, False otherwise). default: true deprecated: true featured_rank: anyOf: - type: integer - type: 'null' title: Featured Rank description: >- 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. examples: - 1 - 2 - 3 created_at: type: string format: date-time title: Created At description: When the listing was created updated_at: type: string format: date-time title: Updated At description: When the listing was last updated published_at: anyOf: - type: string format: date-time - type: 'null' title: Published At description: When the listing was first published total_subscribers: type: integer title: Total Subscribers description: Total number of active subscribers default: 0 total_queries: type: integer title: Total Queries description: Total queries executed across all subscribers default: 0 type: object required: - internal_id - namespace_id - retriever_id - title - description - public_name - available_tiers title: MarketplaceListing description: >- 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 ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false SubscriptionTierConfig: properties: tier: $ref: '#/components/schemas/SubscriptionTier' description: Tier level price_per_month: type: number minimum: 0 title: Price Per Month description: Monthly price in USD (0.0 for free tier) default: 0 limits: $ref: '#/components/schemas/TierLimits' description: Rate limits and quotas for this tier features: items: type: string type: array title: Features description: List of features included in this tier stripe_price_id: anyOf: - type: string - type: 'null' title: Stripe Price Id description: Stripe price ID for paid tiers type: object required: - tier title: SubscriptionTierConfig description: Configuration for a subscription tier. ListingStatus: type: string enum: - draft - published - archived - suspended title: ListingStatus description: Status of a marketplace listing. ListingVisibility: type: string enum: - listed - unlisted title: ListingVisibility description: >- 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. ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. SubscriptionTier: type: string enum: - free - basic - pro - enterprise title: SubscriptionTier description: Subscription tier levels for marketplace offerings. TierLimits: properties: requests_per_minute: anyOf: - type: integer - type: 'null' title: Requests Per Minute description: Maximum requests per minute (None = unlimited) requests_per_hour: anyOf: - type: integer - type: 'null' title: Requests Per Hour description: Maximum requests per hour (None = unlimited) requests_per_day: anyOf: - type: integer - type: 'null' title: Requests Per Day description: Maximum requests per day (None = unlimited) requests_per_month: anyOf: - type: integer - type: 'null' title: Requests Per Month description: Maximum requests per month (None = unlimited) type: object title: TierLimits description: Rate limits and quotas for a subscription tier. securitySchemes: BearerAuth: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.