Get Published Retriever

curl --request GET \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id}/publish \
  --header 'Authorization: <authorization>' \
  --header 'X-Namespace: <x-namespace>'

{
  "retriever_id": "<string>",
  "public_id": "<string>",
  "public_name": "<string>",
  "public_api_key": "<string>",
  "display_config": {
    "title": "<string>",
    "inputs": [
      {
        "field_name": "<string>",
        "field_schema": {
          "type": "string",
          "default": "<unknown>",
          "items": "<unknown>",
          "properties": {},
          "examples": [
            "<unknown>"
          ],
          "description": "<string>",
          "enum": [
            "<unknown>"
          ],
          "required": false
        },
        "label": "<string>",
        "placeholder": "Enter search terms...",
        "helper_text": "Describe the aesthetic, outfit, or vibe you're looking for",
        "suggestions": [
          "streetwear urban",
          "clean girl minimal",
          "summer haul bright"
        ],
        "required": true,
        "order": 0
      }
    ],
    "exposed_fields": [
      "<string>"
    ],
    "description": "Search through thousands of products",
    "logo_url": "https://example.com/logo.png",
    "og_image_url": "https://s3.amazonaws.com/mixpeek-server-dev/org123/ns456/public-retriever-og-images/video-search/og.png",
    "markdowns": [
      {
        "title": "<string>",
        "content": "<string>"
      }
    ],
    "theme": {
      "primary_color": "#007AFF",
      "secondary_color": "#FF6B6B",
      "font_family": "system-ui, -apple-system, sans-serif",
      "background_color": "#FFFFFF",
      "text_color": "#000000"
    },
    "layout": {
      "mode": "grid",
      "columns": 3,
      "gap": "16px"
    },
    "components": {
      "show_search": true,
      "show_filters": false,
      "result_layout": "grid",
      "result_card": {
        "layout": "vertical",
        "show_thumbnail": true,
        "thumbnail_aspect_ratio": "16/9",
        "thumbnail_fit": "cover",
        "show_score": false,
        "truncate_title": 60,
        "truncate_description": 120,
        "field_order": [
          "<string>"
        ]
      }
    },
    "field_config": {}
  },
  "rate_limit_config": {
    "enabled": true,
    "tier": "standard",
    "requests_per_minute": 2,
    "requests_per_hour": 2,
    "requests_per_day": 2,
    "max_results_per_query": 100,
    "enable_ip_limits": false,
    "max_requests_per_ip_hour": 2
  },
  "password_protected": true,
  "is_active": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "retriever_metadata": {
    "stages": [
      {}
    ],
    "collections": [
      {}
    ],
    "capabilities": {}
  }
}

GET

retrievers

{retriever_id}

publish

Get Published Retriever

curl --request GET \
  --url https://api.mixpeek.com/v1/retrievers/{retriever_id}/publish \
  --header 'Authorization: <authorization>' \
  --header 'X-Namespace: <x-namespace>'

{
  "retriever_id": "<string>",
  "public_id": "<string>",
  "public_name": "<string>",
  "public_api_key": "<string>",
  "display_config": {
    "title": "<string>",
    "inputs": [
      {
        "field_name": "<string>",
        "field_schema": {
          "type": "string",
          "default": "<unknown>",
          "items": "<unknown>",
          "properties": {},
          "examples": [
            "<unknown>"
          ],
          "description": "<string>",
          "enum": [
            "<unknown>"
          ],
          "required": false
        },
        "label": "<string>",
        "placeholder": "Enter search terms...",
        "helper_text": "Describe the aesthetic, outfit, or vibe you're looking for",
        "suggestions": [
          "streetwear urban",
          "clean girl minimal",
          "summer haul bright"
        ],
        "required": true,
        "order": 0
      }
    ],
    "exposed_fields": [
      "<string>"
    ],
    "description": "Search through thousands of products",
    "logo_url": "https://example.com/logo.png",
    "og_image_url": "https://s3.amazonaws.com/mixpeek-server-dev/org123/ns456/public-retriever-og-images/video-search/og.png",
    "markdowns": [
      {
        "title": "<string>",
        "content": "<string>"
      }
    ],
    "theme": {
      "primary_color": "#007AFF",
      "secondary_color": "#FF6B6B",
      "font_family": "system-ui, -apple-system, sans-serif",
      "background_color": "#FFFFFF",
      "text_color": "#000000"
    },
    "layout": {
      "mode": "grid",
      "columns": 3,
      "gap": "16px"
    },
    "components": {
      "show_search": true,
      "show_filters": false,
      "result_layout": "grid",
      "result_card": {
        "layout": "vertical",
        "show_thumbnail": true,
        "thumbnail_aspect_ratio": "16/9",
        "thumbnail_fit": "cover",
        "show_score": false,
        "truncate_title": 60,
        "truncate_description": 120,
        "field_order": [
          "<string>"
        ]
      }
    },
    "field_config": {}
  },
  "rate_limit_config": {
    "enabled": true,
    "tier": "standard",
    "requests_per_minute": 2,
    "requests_per_hour": 2,
    "requests_per_day": 2,
    "max_results_per_query": 100,
    "enable_ip_limits": false,
    "max_requests_per_ip_hour": 2
  },
  "password_protected": true,
  "is_active": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "retriever_metadata": {
    "stages": [
      {}
    ],
    "collections": [
      {}
    ],
    "capabilities": {}
  }
}

Headers

Authorization

string

required

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

X-Namespace

string

required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Path Parameters

retriever_id

string

required

ID of the retriever

Response

Successful Response

Response model for GET published retriever.

Returns the full published retriever config including the public API key since the user already has access to it.

retriever_id

string

required

ID of the underlying retriever

public_id

string

required

Public identifier for this published retriever

public_name

string

required

Public URL-safe name

public_api_key

string

required

Public API key (safe to show to retriever owner)

display_config

DisplayConfig · object

required

Display configuration for UI rendering

Show child attributes

display_config.title

string

required

Title/heading for the public search page

display_config.inputs

InputRenderingConfig · object[]

required

List of input fields to render in the search interface. Each input maps to a field in the retriever's input_schema. Frontend uses the field_schema to render the appropriate component type.

Minimum array length: 1

Show child attributes

display_config.inputs.field_name

string

required

Name of the input field (matches retriever input_schema key)

display_config.inputs.field_schema

BucketSchemaField · object

required

Schema definition for this input field. Defines type, description, examples, and validation rules. Frontend uses this to render the appropriate input component (text input, image upload, dropdown, etc.)

Show child attributes

display_config.inputs.field_schema.type

enum<string>

required

Supported data types for bucket schema fields.

Types fall into two categories:

Explicit Types (Type-Safe):
- Provide type guarantees for extractors
- User must pre-classify content
- Compatible with type-specific extractors
Automatic Type (Flexible):
- No type guarantee (runtime detection)
- User doesn't pre-classify content
- Only compatible with multimodal extractors

Available options:

string,

number,

integer,

float,

boolean,

object,

array,

date,

datetime,

json,

file,

text,

image,

audio,

video,

pdf,

document,

spreadsheet,

presentation,

dense_vector,

sparse_vector,

int8_vector,

automatic

display_config.inputs.field_schema.default

unknown

display_config.inputs.field_schema.items

unknown

display_config.inputs.field_schema.properties

Properties · object

display_config.inputs.field_schema.examples

any[] | null

OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible.

display_config.inputs.field_schema.description

string | null

display_config.inputs.field_schema.enum

any[] | null

display_config.inputs.field_schema.required

boolean | null

default:false

display_config.inputs.label

string

required

Human-readable label for the input

display_config.inputs.placeholder

string | null

Placeholder text for the input

Example:

"Enter search terms..."

display_config.inputs.helper_text

string | null

Helper text displayed below the input to guide users

Example:

"Describe the aesthetic, outfit, or vibe you're looking for"

display_config.inputs.suggestions

string[] | null

Pre-filled suggestion chips that users can click to populate the input

Example:

[
  "streetwear urban",
  "clean girl minimal",
  "summer haul bright"
]

display_config.inputs.required

boolean

default:true

Whether this input is required

display_config.inputs.order

integer

default:0

Display order (lower numbers appear first)

Required range: x >= 0

display_config.exposed_fields

string[]

required

List of document metadata fields to show in results. Only these fields are returned to end users.

Minimum array length: 1

display_config.description

string | null

Optional description/subtitle for the page

Example:

"Search through thousands of products"

display_config.logo_url

string | null

URL to logo image

Example:

"https://example.com/logo.png"

display_config.og_image_url

string | null

URL to auto-generated social preview/OG image

Example:

"https://s3.amazonaws.com/mixpeek-server-dev/org123/ns456/public-retriever-og-images/video-search/og.png"

display_config.markdowns

MarkdownContent · object[]

Array of markdown content sections for documentation, guides, or informational modals. Each section has a title and markdown-formatted content. Displayed in modals, expandable sections, or tabs on the public interface. Examples: 'How it Works', 'Search Guide', 'About', 'FAQ', etc.

Show child attributes

display_config.markdowns.title

string

required

Title for the markdown content section

Required string length: 1 - 200

display_config.markdowns.content

string

required

Markdown-formatted content. Supports standard markdown syntax including headers, lists, links, images, code blocks, and emphasis. Limited to 50KB to prevent database issues.

Required string length: 1 - 50000

display_config.theme

ThemeConfig · object

Theme/styling configuration

Show child attributes

display_config.theme.primary_color

string

default:#007AFF

Primary brand color (hex code)

display_config.theme.secondary_color

string | null

Secondary/accent color (hex code)

Example:

"#FF6B6B"

display_config.theme.font_family

string

default:system-ui, -apple-system, sans-serif

Font family for text

display_config.theme.background_color

string

default:#FFFFFF

Background color (hex code)

display_config.theme.text_color

string

default:#000000

Primary text color (hex code)

display_config.layout

LayoutConfig · object

Layout configuration for results

Show child attributes

display_config.layout.mode

string

default:grid

Display mode for results

display_config.layout.columns

integer

default:3

Number of columns for grid/masonry layouts

Required range: 1 <= x <= 6

display_config.layout.gap

string

default:16px

Gap between items

display_config.components

ComponentsConfig · object

Configuration for UI components including search inputs, filters, and result card display options.

Show child attributes

display_config.components.show_search

boolean

default:true

Whether to show search input fields

display_config.components.show_filters

boolean

default:false

Whether to show filters sidebar

display_config.components.result_layout

string

default:grid

Layout mode for results display

display_config.components.result_card

ResultCardProperties · object

Configuration for result card display

Show child attributes

display_config.components.result_card.layout

string

default:vertical

Card layout orientation

display_config.components.result_card.show_thumbnail

boolean

default:true

Whether to show thumbnail image in results

display_config.components.result_card.thumbnail_aspect_ratio

string

default:16/9

Aspect ratio for thumbnail images

display_config.components.result_card.thumbnail_fit

string

default:cover

How thumbnail should fit in container

display_config.components.result_card.show_score

boolean

default:false

Whether to display relevance score

display_config.components.result_card.truncate_title

integer | null

Maximum characters for title before truncation

Required range: x >= 1

Example:

60

display_config.components.result_card.truncate_description

integer | null

Maximum characters for description before truncation

Required range: x >= 1

Example:

120

display_config.components.result_card.field_order

string[]

Order of fields to display in result card. Fields not in this list won't be shown. Must be subset of exposed_fields.

display_config.field_config

Field Config · object

Configuration for how each field should be displayed. Keys are field names (must be subset of exposed_fields). Values are FieldConfig objects specifying format and display options.

Show child attributes

display_config.field_config.{key}

FieldConfig · object

Configuration for how to display a specific field in results.

Show child attributes

display_config.field_config.{key}.format

enum<string>

required

Format type for this field (text, image, date, number, etc.)

Available options:

text,

image,

date,

number,

url,

boolean,

array,

object

display_config.field_config.{key}.format_options

FieldFormatOptions · object

Format-specific display options

Show child attributes

display_config.field_config.{key}.format_options.label

string | null

Display label for this field

Example:

"Title"

display_config.field_config.{key}.format_options.show_empty

boolean

default:true

Whether to show the field if value is empty/null

display_config.field_config.{key}.format_options.truncate_chars

integer | null

Maximum characters before truncation (for text fields)

Required range: x >= 1

Example:

60

display_config.field_config.{key}.format_options.width

integer | null

Image width in pixels

Required range: x >= 1

Example:

400

display_config.field_config.{key}.format_options.height

integer | null

Image height in pixels

Required range: x >= 1

Example:

300

display_config.field_config.{key}.format_options.lazy_load

boolean

default:true

Enable lazy loading for images (default: true)

display_config.field_config.{key}.format_options.aspect_ratio

string | null

Aspect ratio for image container

Example:

"16/9"

display_config.field_config.{key}.format_options.object_fit

string

default:cover

CSS object-fit property for images

display_config.field_config.{key}.format_options.date_format

string

default:relative

Date format type: 'iso', 'relative', or custom format string

display_config.field_config.{key}.format_options.decimals

integer | null

Number of decimal places

Required range: x >= 0

Example:

0

display_config.field_config.{key}.format_options.prefix

string | null

Prefix for number display

Example:

"$"

display_config.field_config.{key}.format_options.suffix

string | null

Suffix for number display

Example:

"%"

display_config.field_config.{key}.format_options.open_in_new_tab

boolean

default:true

Open URLs in new tab (default: true)

display_config.field_config.{key}.format_options.show_domain

boolean

default:false

Show domain instead of full URL

display_config.field_config.{key}.format_options.true_label

string

default:Yes

Label for true values

display_config.field_config.{key}.format_options.false_label

string

default:No

Label for false values

display_config.field_config.{key}.format_options.separator

string

default:,

Separator for array items (default: ', ')

display_config.field_config.{key}.format_options.max_items

integer | null

Maximum array items to display

Required range: x >= 1

rate_limit_config

RateLimitConfig · object

required

Rate limiting configuration

Show child attributes

rate_limit_config.enabled

boolean

default:true

Enable rate limiting for this published retriever. Set to False to disable all rate limiting (not recommended for public retrievers).

rate_limit_config.tier

enum<string>

default:standard

Rate limit tier preset. STANDARD (default): 60/min, 1k/hour, 10k/day. ELEVATED: 300/min, 10k/hour, 100k/day. ENTERPRISE: 1000/min, 50k/hour, 500k/day. UNLIMITED: No limits. Custom limits override tier defaults.

Available options:

standard,

elevated,

enterprise,

unlimited

rate_limit_config.requests_per_minute

integer | null

Maximum requests per minute (OPTIONAL). If not specified, uses tier default. If specified, overrides tier default.

Required range: x >= 1

rate_limit_config.requests_per_hour

integer | null

Maximum requests per hour (OPTIONAL). If not specified, uses tier default. If specified, overrides tier default.

Required range: x >= 1

rate_limit_config.requests_per_day

integer | null

Maximum requests per day (OPTIONAL). If not specified, uses tier default. If specified, overrides tier default.

Required range: x >= 1

rate_limit_config.max_results_per_query

integer

default:100

Maximum number of results per search query (1-1000)

Required range: 1 <= x <= 1000

rate_limit_config.enable_ip_limits

boolean

default:false

Enable IP-based rate limiting in addition to retriever-level limits. Useful for preventing individual IPs from monopolizing the retriever.

rate_limit_config.max_requests_per_ip_hour

integer | null

Maximum requests per IP address per hour (OPTIONAL). Only enforced if enable_ip_limits=True. Recommended: 100-500 for standard tier, 1000+ for elevated/enterprise.

Required range: x >= 1

password_protected

boolean

required

Whether password protection is enabled

is_active

boolean

required

Whether the published retriever is active

created_at

string<date-time>

required

Timestamp when published

updated_at

string<date-time>

required

Timestamp when last updated

retriever_metadata

RetrieverMetadata · object

Optional technical metadata about the retriever

Show child attributes

retriever_metadata.stages

Stages · object[]

Pipeline stages used in this retriever

retriever_metadata.collections

Collections · object[]

Collections and feature extractors used

retriever_metadata.capabilities

Capabilities · object

Capabilities and features of this retriever

Get Organization Publish Stats Publish Retriever

⌘I

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Analytics

Resource Search

Inference

Agent Sessions

Tasks

Webhooks

Notifications

Triggers

Get Published Retriever

Headers

Path Parameters

Response