Sign in

v5

OpenAPI 3.1.02026-08-025631,1012.8 MB
Published Retrievers

Update Published Retriever

Update published retriever configuration.

Allows updating display config, rate limits, exposed fields, and password protection. The public API key and public name cannot be changed (unpublish and republish instead).

patch/v1/retrievers/{retriever_id}/publish

Path parameters

retriever_idstring required

ID of the retriever

ID of the retriever

Request body

password_secret_namestring nullable

Update or remove password protection (set to empty string to remove)

is_activeboolean nullable

Activate or deactivate the published retriever

tagsstring[] nullable

Update tags for categorizing this retriever

categorystring nullable

Update the primary category for this retriever

Example request

{
  "display_config": {
    "components": {
      "result_card": {
        "card_click_action": "viewDetails",
        "field_order": [
          "title",
          "description",
          "price"
        ],
        "layout": "vertical",
        "show_find_similar": true,
        "show_thumbnail": true
      },
      "result_layout": "grid",
      "show_hero": true,
      "show_results_header": true,
      "show_search": true
    },
    "custom_cta": {
      "label": "Search Tips",
      "markdown_content": "# Search Tips\n\n- Use quotes for exact phrases\n- Try descriptive terms"
    },
    "description": "Search through our product catalog",
    "exposed_fields": [
      "title",
      "description",
      "price",
      "image_url"
    ],
    "external_links": [
      {
        "name": "GitHub Repository",
        "url": "https://github.com/mixpeek/product-search"
      },
      {
        "name": "Blog Post",
        "url": "https://blog.mixpeek.com/building-product-search"
      }
    ],
    "field_config": {
      "price": {
        "format": "number",
        "format_options": {
          "decimals": 2,
          "label": "Price",
          "prefix": "$"
        }
      },
      "title": {
        "format": "text",
        "format_options": {
          "label": "Product Name",
          "truncate_chars": 60
        }
      }
    },
    "field_mappings": {
      "thumbnail": "image_url",
      "title": "title"
    },
    "inputs": [
      {
        "field_name": "query",
        "field_schema": {
          "description": "Search query",
          "examples": [
            "wireless headphones",
            "laptop"
          ],
          "type": "string"
        },
        "input_type": "text",
        "label": "Search Products",
        "order": 0,
        "placeholder": "What are you looking for?",
        "required": true
      }
    ],
    "layout": {
      "columns": 3,
      "gap": "16px",
      "mode": "grid"
    },
    "logo_url": "https://example.com/logo.png",
    "markdowns": [
      {
        "content": "# AI-Powered Product Search\n\nOur search uses **machine learning** to understand your queries and find the most relevant products.\n\n## Features\n\n- **Semantic Search**: Understands meaning, not just keywords\n- **Visual Search**: Upload images to find similar products\n- **Smart Filters**: Automatically suggests relevant filters",
        "title": "How it Works"
      },
      {
        "content": "## Tips for Better Results\n\n1. Use descriptive terms (e.g., \"wireless noise-canceling headphones\")\n2. Try different keywords if you don't find what you're looking for\n3. Use filters to narrow down results\n\n*Happy searching!*",
        "title": "Search Guide"
      }
    ],
    "template_type": "media-search",
    "theme": {
      "border_radius": "12px",
      "card_style": "elevated",
      "font_family": "Inter, sans-serif",
      "primary_color": "#007AFF"
    },
    "title": "Product Search"
  },
  "rate_limit_config": {
    "description": "Standard tier (default) - 10/min, 100/hour, 1k/day",
    "enabled": true,
    "max_results_per_query": 50,
    "tier": "standard"
  }
}

Response

Successful Response

retriever_idstring required

ID of the underlying retriever

public_idstring required

Public identifier for this published retriever

public_namestring required

Public URL-safe name

descriptionstring nullable

Description of this public retriever

icon_base64string nullable

Base64 encoded icon/favicon for this retriever

public_api_keystring nullable

DEPRECATED: Public API key (prk_). API keys are no longer required for public retriever access. For SDK access, use ret_sk_ keys.

password_protectedboolean required

Whether password protection is enabled

is_activeboolean required

Whether the published retriever is active

tagsstring[]

Tags for categorizing this retriever

categorystring nullable

Primary category for this retriever

created_atstring date-time required

Timestamp when published

updated_atstring date-time required

Timestamp when last updated

Example response

{
  "display_config": {
    "components": {
      "result_card": {
        "card_click_action": "viewDetails",
        "field_order": [
          "title",
          "description",
          "price"
        ],
        "layout": "vertical",
        "show_find_similar": true,
        "show_thumbnail": true
      },
      "result_layout": "grid",
      "show_hero": true,
      "show_results_header": true,
      "show_search": true
    },
    "custom_cta": {
      "label": "Search Tips",
      "markdown_content": "# Search Tips\n\n- Use quotes for exact phrases\n- Try descriptive terms"
    },
    "description": "Search through our product catalog",
    "exposed_fields": [
      "title",
      "description",
      "price",
      "image_url"
    ],
    "external_links": [
      {
        "name": "GitHub Repository",
        "url": "https://github.com/mixpeek/product-search"
      },
      {
        "name": "Blog Post",
        "url": "https://blog.mixpeek.com/building-product-search"
      }
    ],
    "field_config": {
      "price": {
        "format": "number",
        "format_options": {
          "decimals": 2,
          "label": "Price",
          "prefix": "$"
        }
      },
      "title": {
        "format": "text",
        "format_options": {
          "label": "Product Name",
          "truncate_chars": 60
        }
      }
    },
    "field_mappings": {
      "thumbnail": "image_url",
      "title": "title"
    },
    "inputs": [
      {
        "field_name": "query",
        "field_schema": {
          "description": "Search query",
          "examples": [
            "wireless headphones",
            "laptop"
          ],
          "type": "string"
        },
        "input_type": "text",
        "label": "Search Products",
        "order": 0,
        "placeholder": "What are you looking for?",
        "required": true
      }
    ],
    "layout": {
      "columns": 3,
      "gap": "16px",
      "mode": "grid"
    },
    "logo_url": "https://example.com/logo.png",
    "markdowns": [
      {
        "content": "# AI-Powered Product Search\n\nOur search uses **machine learning** to understand your queries and find the most relevant products.\n\n## Features\n\n- **Semantic Search**: Understands meaning, not just keywords\n- **Visual Search**: Upload images to find similar products\n- **Smart Filters**: Automatically suggests relevant filters",
        "title": "How it Works"
      },
      {
        "content": "## Tips for Better Results\n\n1. Use descriptive terms (e.g., \"wireless noise-canceling headphones\")\n2. Try different keywords if you don't find what you're looking for\n3. Use filters to narrow down results\n\n*Happy searching!*",
        "title": "Search Guide"
      }
    ],
    "template_type": "media-search",
    "theme": {
      "border_radius": "12px",
      "card_style": "elevated",
      "font_family": "Inter, sans-serif",
      "primary_color": "#007AFF"
    },
    "title": "Product Search"
  },
  "rate_limit_config": {
    "description": "Standard tier (default) - 10/min, 100/hour, 1k/day",
    "enabled": true,
    "max_results_per_query": 50,
    "tier": "standard"
  },
  "retriever_metadata": {
    "stages": [
      {
        "stage_name": "feature_filter",
        "stage_type": "filter"
      },
      {
        "stage_name": "llm_filter",
        "stage_type": "filter"
      }
    ],
    "collections": [
      {
        "collection_id": "col_abc123",
        "collection_name": "Products",
        "feature_extractor": {
          "name": "multimodal_extractor",
          "version": "v1"
        }
      }
    ],
    "capabilities": {
      "multi_stage_pipeline": true,
      "stage_count": 2,
      "supports_image_search": true,
      "supports_text_search": true
    }
  }
}