> ## 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. # Update an App > Partially update an App configuration (saved as draft). All fields are optional — only the fields you provide are updated. Updates are draft by default. Set `publish: true` to apply and publish in a single call. ## OpenAPI ````yaml patch /v1/apps/{app_id} 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: [] paths: /v1/apps/{app_id}: patch: tags: - Apps summary: Update an App description: |- Partially update an App configuration (saved as draft). All fields are optional — only the fields you provide are updated. Updates are draft by default. Set `publish: true` to apply and publish in a single call. operationId: update_app_v1_apps__app_id__patch parameters: - name: app_id in: path required: true schema: type: string description: App ID (e.g. app_abc123def456) title: App Id description: App ID (e.g. app_abc123def456) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAppRequest' responses: '200': description: Updated App configuration content: application/json: schema: $ref: '#/components/schemas/AppResponse' '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: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: UpdateAppRequest: properties: slug: anyOf: - type: string maxLength: 60 minLength: 3 pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$ - type: 'null' title: Slug meta: anyOf: - $ref: '#/components/schemas/PageMeta' - type: 'null' auth_config: anyOf: - $ref: '#/components/schemas/AuthConfig-Input' - type: 'null' build_config: anyOf: - $ref: '#/components/schemas/BuildConfig' - type: 'null' monitoring_config: anyOf: - $ref: '#/components/schemas/MonitoringConfig' - type: 'null' is_active: anyOf: - type: boolean - type: 'null' title: Is Active publish: type: boolean title: Publish description: When true, applies the update and immediately publishes. default: false template: anyOf: - type: string - type: 'null' title: Template deprecated: true sections: anyOf: - items: $ref: '#/components/schemas/SectionConfig' type: array - type: 'null' title: Sections deprecated: true custom_html: anyOf: - type: string - type: 'null' title: Custom Html deprecated: true hero: anyOf: - $ref: '#/components/schemas/HeroConfig' - type: 'null' deprecated: true theme: anyOf: - $ref: '#/components/schemas/ThemeConfig' - type: 'null' deprecated: true seo: anyOf: - $ref: '#/components/schemas/SEOConfig' - type: 'null' deprecated: true stats: anyOf: - items: $ref: '#/components/schemas/StatItem' type: array - type: 'null' title: Stats deprecated: true featured_gallery: anyOf: - $ref: '#/components/schemas/FeaturedGalleryConfig-Input' - type: 'null' deprecated: true tabs: anyOf: - items: $ref: '#/components/schemas/PageTab-Input' type: array - type: 'null' title: Tabs deprecated: true password_secret_name: anyOf: - type: string - type: 'null' title: Password Secret Name deprecated: true type: object title: UpdateAppRequest description: |- Request to update an existing App (all fields optional). For deploy-based apps, typically only ``auth_config``, ``build_config``, ``meta``, and ``slug`` are updated here. Code changes go through the deploy pipeline. Legacy page-builder fields are accepted for backward compatibility but **deprecated**. AppResponse: properties: app_id: type: string title: App Id slug: type: string title: Slug url: type: string title: Url description: Canonical published URL (https://{slug}.mxp.co) meta: $ref: '#/components/schemas/PageMeta' is_active: type: boolean title: Is Active version: type: integer title: Version has_unpublished_changes: type: boolean title: Has Unpublished Changes default: false custom_domains: items: $ref: '#/components/schemas/CustomDomainConfig' type: array title: Custom Domains auth_config: anyOf: - $ref: '#/components/schemas/AuthConfig-Output' - type: 'null' build_config: anyOf: - $ref: '#/components/schemas/BuildConfig' - type: 'null' monitoring_config: anyOf: - $ref: '#/components/schemas/MonitoringConfig' - type: 'null' repo_url: anyOf: - type: string - type: 'null' title: Repo Url repo_branch: anyOf: - type: string - type: 'null' title: Repo Branch github_installation_id: anyOf: - type: integer - type: 'null' title: Github Installation Id versions: items: $ref: '#/components/schemas/VersionRecord' type: array title: Versions description: Deploy version history with timestamps and environment info environments: additionalProperties: true type: object title: Environments created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At template: type: string title: Template deprecated: true sections: items: $ref: '#/components/schemas/SectionConfig' type: array title: Sections deprecated: true custom_html: anyOf: - type: string - type: 'null' title: Custom Html deprecated: true hero: anyOf: - $ref: '#/components/schemas/HeroConfig' - type: 'null' deprecated: true theme: $ref: '#/components/schemas/ThemeConfig' deprecated: true seo: anyOf: - $ref: '#/components/schemas/SEOConfig' - type: 'null' deprecated: true stats: items: $ref: '#/components/schemas/StatItem' type: array title: Stats deprecated: true featured_gallery: anyOf: - $ref: '#/components/schemas/FeaturedGalleryConfig-Output' - type: 'null' deprecated: true tabs: items: $ref: '#/components/schemas/PageTab-Output' type: array title: Tabs deprecated: true password_protected: type: boolean title: Password Protected deprecated: true type: object required: - app_id - slug - url - meta - is_active - version - custom_domains - auth_config - build_config - environments - created_at - updated_at - template - sections - custom_html - hero - theme - seo - stats - featured_gallery - tabs - password_protected title: AppResponse description: |- Response model for an App. Deploy-based apps use ``versions``, ``environments``, ``build_config``, and ``auth_config``. Legacy page-builder fields (``template``, ``sections``, ``custom_html``, ``hero``, ``theme``, ``seo``, ``stats``, ``featured_gallery``, ``tabs``, ``password_protected``) are included for backward compatibility but **deprecated**. 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 HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PageMeta: properties: title: type: string title: Title description: Page title displayed in the browser tab and page header. examples: - My Product Search - Brand Compliance Dashboard description: anyOf: - type: string - type: 'null' title: Description description: Short page description shown in the page header or subtitle area. examples: - Search across 10k+ product images logo_url: anyOf: - type: string - type: 'null' title: Logo Url description: URL of the logo displayed in the page header. examples: - https://cdn.example.com/logo.png favicon_url: anyOf: - type: string - type: 'null' title: Favicon Url description: URL of the favicon for the browser tab. examples: - https://cdn.example.com/favicon.ico indexable: anyOf: - type: boolean - type: 'null' title: Indexable description: >- When true, opts the app in to search-engine and AI crawler indexing. Canvas serves an Allow robots.txt and omits X-Robots-Tag/noindex. Defaults to false (noindex) for all apps. examples: - false - true type: object required: - title title: PageMeta description: >- Page-level metadata (REQUIRED when creating a page). This object is separate from the optional ``seo`` field. ``meta`` controls the visible page chrome (browser tab title, logo, favicon), while ``seo`` controls search-engine tags (og:title, og:description, etc.). AuthConfig-Input: properties: mode: type: string enum: - public - clerk - password - api_key - jwt - sso_oidc - sso_saml title: Mode description: Authentication mode default: public clerk_org_id: anyOf: - type: string - type: 'null' title: Clerk Org Id description: Clerk Organization ID for this app (auto-provisioned) clerk_allowed_providers: items: type: string type: array title: Clerk Allowed Providers description: 'Enabled auth providers: google, github, email' password: anyOf: - type: string - type: 'null' title: Password description: >- Plaintext password (write-only — hashed before storage, never returned in responses) password_hash: anyOf: - type: string - type: 'null' title: Password Hash description: >- Bcrypt hash of the password (internal — never exposed in API responses) saml_idp_metadata_url: anyOf: - type: string - type: 'null' title: Saml Idp Metadata Url saml_sp_entity_id: anyOf: - type: string - type: 'null' title: Saml Sp Entity Id saml_acs_url: anyOf: - type: string - type: 'null' title: Saml Acs Url oidc_issuer: anyOf: - type: string - type: 'null' title: Oidc Issuer oidc_client_id: anyOf: - type: string - type: 'null' title: Oidc Client Id oidc_client_secret_name: anyOf: - type: string - type: 'null' title: Oidc Client Secret Name description: Secrets vault key name (never stored inline) oidc_scopes: items: type: string type: array title: Oidc Scopes jwt_jwks_url: anyOf: - type: string - type: 'null' title: Jwt Jwks Url jwt_audience: anyOf: - type: string - type: 'null' title: Jwt Audience jwt_issuer: anyOf: - type: string - type: 'null' title: Jwt Issuer api_keys: items: additionalProperties: true type: object type: array title: Api Keys type: object title: AuthConfig description: >- End-user authentication configuration for an App. Supported modes: - ``public``: No authentication required (default) - ``clerk``: Managed auth via Clerk Organizations — handles Google, GitHub, email/password signup/login. Each canvas app maps to a Clerk Organization. Users are synced to canvas_users via Clerk webhooks. - ``password``: Simple password gate — visitors must enter a password to access the app. The password is hashed (bcrypt) before storage. - ``api_key``, ``jwt``, ``sso_oidc``, ``sso_saml``: Advanced modes retained for future use. BuildConfig: properties: entry: type: string title: Entry description: Build entry point default: src/layout.jsx framework: type: string const: react title: Framework default: react tailwind: type: boolean title: Tailwind default: true env_vars: additionalProperties: type: string type: object title: Env Vars description: >- Build-time environment variables injected into the app. Set MIXPEEK_API_KEY here to enable the /_api server-side proxy — without it the proxy falls back to the canvas server's default key. NOTE: every key here EXCEPT MIXPEEK_API_KEY is injected into the browser's window.__MIXPEEK__. For third-party secrets that must stay server-side (e.g. SERPAPI_KEY for a /functions/* handler), use ``secrets`` below, not ``env_vars``. secrets: additionalProperties: type: string type: object title: Secrets description: >- Server-only secrets for the app's /functions/* server-side handlers, exposed to them as ``ctx.env``. NEVER injected into the browser window.__MIXPEEK__ and masked ('***') in API responses. Use for third-party API keys (e.g. SERPAPI_KEY). asset_prefix: anyOf: - type: string - type: 'null' title: Asset Prefix description: CDN asset prefix once deployed type: object title: BuildConfig description: |- JSX build configuration for an App. Phase 1: schema only. Phase 3: used by the build pipeline Celery task. MonitoringConfig: properties: enabled: type: boolean title: Enabled description: Master switch — must be true for any monitoring to activate default: true error_boundary_enabled: type: boolean title: Error Boundary Enabled description: >- Wrap app in a React Error Boundary that shows a fallback UI on crash. Client-side only — no data is sent externally. Enabled by default. default: true sentry_enabled: type: boolean title: Sentry Enabled description: >- Capture unhandled exceptions to Mixpeek-internal Sentry. No PII is captured (beforeSend strips it). default: true posthog_enabled: type: boolean title: Posthog Enabled description: >- Capture pageviews and error counts to Mixpeek-internal PostHog. No text content, no session recordings. default: true custom_error_message: anyOf: - type: string - type: 'null' title: Custom Error Message description: Custom message shown in the Error Boundary fallback UI auto_fix_enabled: type: boolean title: Auto Fix Enabled description: >- When true, error spikes trigger the Claude-powered auto-fix pipeline. Requires source_files on the latest version or a connected GitHub repo. default: true type: object title: MonitoringConfig description: >- Opt-in monitoring configuration for a Canvas app. All monitoring is off by default except ``error_boundary_enabled``, which is a client-side UX safety net (shows fallback UI instead of blank page) and sends no data externally. When ``sentry_enabled`` or ``posthog_enabled`` are turned on, monitoring data is sent to **Mixpeek-internal** Sentry/PostHog — never to the customer's own observability stack. PII is stripped via ``beforeSend`` / ``mask_all_text``, and session replay is always off. SectionConfig: properties: section_id: type: string title: Section Id description: Auto-generated section identifier type: type: string title: Type description: >- Section type: 'hero', 'stats-bar', 'featured-gallery', 'search-tabs', 'results-grid', 'results-list', 'markdown-content', 'iframe-embed' props: additionalProperties: true type: object title: Props description: Section-specific configuration properties order: anyOf: - type: integer - type: 'null' title: Order description: Explicit render order; falls back to array position if omitted type: object required: - type title: SectionConfig description: A single section/block in a page layout. HeroConfig: properties: headline: type: string title: Headline description: Main headline text subheadline: anyOf: - type: string - type: 'null' title: Subheadline description: Optional subheadline text background_type: type: string enum: - image - video - gradient - solid title: Background Type description: Background type default: solid background_url: anyOf: - type: string - type: 'null' title: Background Url description: URL for image or video background background_color: anyOf: - type: string - type: 'null' title: Background Color description: Background color for solid/gradient text_color: type: string title: Text Color description: Hero text color default: '#FFFFFF' logo_url: anyOf: - type: string - type: 'null' title: Logo Url description: Logo URL displayed in hero height: type: string title: Height description: Hero section height default: 420px cta_label: anyOf: - type: string - type: 'null' title: Cta Label description: Call-to-action button label cta_url: anyOf: - type: string - type: 'null' title: Cta Url description: Call-to-action button URL type: object required: - headline title: HeroConfig description: Hero section configuration for a page. ThemeConfig: properties: primary_color: type: string title: Primary Color description: Primary brand color (hex code) default: '#007AFF' examples: - '#007AFF' - '#FF6B6B' - '#4ECDC4' secondary_color: anyOf: - type: string - type: 'null' title: Secondary Color description: Secondary/accent color (hex code) examples: - '#FF6B6B' - '#95E1D3' font_family: type: string title: Font Family description: Font family for text default: system-ui, -apple-system, sans-serif examples: - Inter, sans-serif - Roboto, sans-serif background_color: type: string title: Background Color description: Background color (hex code) default: '#FFFFFF' text_color: type: string title: Text Color description: Primary text color (hex code) default: '#374151' heading_font_family: anyOf: - type: string - type: 'null' title: Heading Font Family description: Optional separate font family for headings examples: - Georgia, serif - Playfair Display, serif surface_color: anyOf: - type: string - type: 'null' title: Surface Color description: Surface/card background color (hex code) examples: - '#F9FAFB' - '#F3F4F6' muted_color: anyOf: - type: string - type: 'null' title: Muted Color description: Muted/secondary text color (hex code) examples: - '#6B7280' - '#9CA3AF' border_color: anyOf: - type: string - type: 'null' title: Border Color description: Border color for cards and elements (hex code) examples: - '#E5E7EB' - '#D1D5DB' border_radius: anyOf: - type: string - type: 'null' title: Border Radius description: Default border radius for cards and elements default: 12px examples: - 8px - 12px - 16px - 24px card_style: anyOf: - type: string - type: 'null' title: Card Style description: >- Card visual style: elevated (shadow), flat (no shadow), bordered, or glass (frosted glass effect) default: elevated examples: - elevated - flat - bordered - glass card_hover_effect: anyOf: - type: string - type: 'null' title: Card Hover Effect description: 'Card hover animation effect: lift (move up), glow, scale, or none' default: lift examples: - lift - glow - scale - none type: object title: ThemeConfig description: >- Theme configuration for public retriever UI. Defines colors, fonts, and visual styling for the public search interface. SEOConfig: properties: meta_title: anyOf: - type: string maxLength: 60 - type: 'null' title: Meta Title description: >- SEO-optimized page title (50-60 chars recommended). Auto-generated from display_config.title + site_name if not provided. examples: - Fitness Video Search | Mixpeek - Product Catalog | Your Brand meta_description: anyOf: - type: string maxLength: 160 - type: 'null' title: Meta Description description: >- Meta description for search engine snippets (max 160 chars). Auto-generated from display_config.description if not provided. examples: - >- Search and discover fitness videos using AI-powered semantic search. - Browse our product catalog with intelligent visual search. keywords: items: type: string type: array title: Keywords description: >- Relevant keywords for search engines. Auto-inferred from title, description, and retriever tags. examples: - - fitness - yoga - workout - exercise videos - - products - catalog - search - e-commerce og_image_url: anyOf: - type: string - type: 'null' title: Og Image Url description: >- URL to OG image for social previews (1200x630px recommended). Auto-generated and uploaded to public S3 bucket during publishing. examples: - >- https://mixpeek-public-pages.s3.amazonaws.com/org/ns/og/video-search/og.png og_image_alt: anyOf: - type: string maxLength: 200 - type: 'null' title: Og Image Alt description: Alt text for OG image (accessibility and SEO) examples: - Fitness video search interface - Product catalog preview og_type: type: string title: Og Type description: Open Graph content type default: website examples: - website - article - product twitter_card: type: string title: Twitter Card description: Twitter card display style default: summary_large_image examples: - summary - summary_large_image - app twitter_site: anyOf: - type: string - type: 'null' title: Twitter Site description: Twitter @handle for the site default: '@mixpeek' examples: - '@mixpeek' - '@yourbrand' twitter_creator: anyOf: - type: string - type: 'null' title: Twitter Creator description: Twitter @handle for content creator (optional) examples: - '@johndoe' - '@yourbrand' robots: type: string title: Robots description: >- Robots meta directive for search engine crawlers. Use 'noindex, nofollow' to hide from search engines. default: index, follow examples: - index, follow - noindex, nofollow - index, nofollow canonical_url: anyOf: - type: string - type: 'null' title: Canonical Url description: >- Canonical URL if different from default. Auto-set to https://mxp.co/r/{public_name} if not provided. examples: - https://yourdomain.com/search - https://mxp.co/r/video-search site_name: type: string title: Site Name description: Site name for OG tags and branding default: Mixpeek examples: - Mixpeek - Your Brand - Company Name author: anyOf: - type: string - type: 'null' title: Author description: Content author/creator name examples: - Mixpeek - Your Organization locale: type: string title: Locale description: Content language/locale default: en_US examples: - en_US - en_GB - es_ES - fr_FR logo_url: anyOf: - type: string - type: 'null' title: Logo Url description: >- URL to organization/brand logo for SEO and branding. Used in structured data and can be displayed in search results. examples: - https://example.com/logo.png - https://cdn.mixpeek.com/logos/acme.png favicon_url: anyOf: - type: string - type: 'null' title: Favicon Url description: >- URL to favicon/icon for the public retriever page. Recommended sizes: 32x32, 48x48, or 180x180 for Apple touch icon. examples: - https://example.com/favicon.ico - https://cdn.mixpeek.com/icons/acme.png structured_data: $ref: '#/components/schemas/StructuredDataConfig' description: Schema.org structured data for rich search results type: object title: SEOConfig description: |- SEO configuration for public retriever discoverability. Auto-generated during publishing with sensible defaults inferred from the retriever's display_config. All fields can be overridden manually. This configuration controls how the public retriever appears in: - Search engine results (Google, Bing, etc.) - Social media shares (Twitter, Facebook, LinkedIn) - Link previews in messaging apps examples: - author: Mixpeek favicon_url: https://example.com/favicon.ico keywords: - fitness - yoga - workout - exercise videos locale: en_US logo_url: https://example.com/logo.png meta_description: Search and discover fitness videos using AI-powered semantic search. meta_title: Fitness Video Search | Mixpeek og_image_alt: Fitness video search interface og_image_url: https://mixpeek-public-pages.s3.amazonaws.com/og.png og_type: website robots: index, follow site_name: Mixpeek structured_data: additional_properties: applicationCategory: Search type: WebApplication twitter_card: summary_large_image twitter_site: '@mixpeek' StatItem: properties: label: type: string title: Label description: Stat label (e.g. 'Total Ads') value: type: string title: Value description: Stat value (e.g. '12,400+') type: object required: - label - value title: StatItem description: A single stat item for the stats bar. FeaturedGalleryConfig-Input: properties: enabled: type: boolean title: Enabled description: Whether the featured gallery is shown default: true title: type: string title: Title description: Gallery section title default: Featured retriever_id: anyOf: - type: string - type: 'null' title: Retriever Id description: Internal retriever ID (defaults to first tab's retriever) public_name: anyOf: - type: string - type: 'null' title: Public Name description: Marketplace catalog public_name for gallery execution default_inputs: additionalProperties: true type: object title: Default Inputs description: Default inputs to auto-execute when page loads layout: $ref: '#/components/schemas/LayoutConfig' description: Layout configuration for gallery results field_config: additionalProperties: $ref: '#/components/schemas/FieldConfig' type: object title: Field Config description: Field display configuration for gallery results type: object title: FeaturedGalleryConfig description: Configuration for the featured gallery section. PageTab-Input: properties: tab_id: type: string title: Tab Id description: Unique identifier for this tab label: type: string title: Label description: Display label for the tab retriever_id: anyOf: - type: string - type: 'null' title: Retriever Id description: Internal retriever ID (use for private retrievers) public_name: anyOf: - type: string - type: 'null' title: Public Name description: Marketplace catalog public_name (proxies execution via public API) description: anyOf: - type: string - type: 'null' title: Description description: Optional tab description shown as subtitle display_config: $ref: '#/components/schemas/DisplayConfig-Input' description: Display configuration for this tab's search UI type: object required: - tab_id - label - display_config title: PageTab description: A single tab in a Page. CustomDomainConfig: properties: domain: type: string title: Domain description: Customer domain (e.g. 'search.acme.com') status: type: string enum: - pending - verifying - provisioning_tls - active title: Status description: Domain verification and TLS lifecycle state default: pending verification_token: anyOf: - type: string - type: 'null' title: Verification Token description: TXT record value for DNS ownership verification cname_target: anyOf: - type: string - type: 'null' title: Cname Target description: CNAME target (e.g. '{slug}.mxp.co') tls_cert_id: anyOf: - type: string - type: 'null' title: Tls Cert Id description: TLS certificate reference tls_expires_at: anyOf: - type: string format: date-time - type: 'null' title: Tls Expires At description: TLS cert expiry verified_at: anyOf: - type: string format: date-time - type: 'null' title: Verified At description: When domain was verified is_primary: type: boolean title: Is Primary description: Whether this is the primary domain default: false type: object required: - domain title: CustomDomainConfig description: A single custom domain attached to an App. AuthConfig-Output: properties: mode: type: string enum: - public - clerk - password - api_key - jwt - sso_oidc - sso_saml title: Mode description: Authentication mode default: public clerk_org_id: anyOf: - type: string - type: 'null' title: Clerk Org Id description: Clerk Organization ID for this app (auto-provisioned) clerk_allowed_providers: items: type: string type: array title: Clerk Allowed Providers description: 'Enabled auth providers: google, github, email' password_hash: anyOf: - type: string - type: 'null' title: Password Hash description: >- Bcrypt hash of the password (internal — never exposed in API responses) saml_idp_metadata_url: anyOf: - type: string - type: 'null' title: Saml Idp Metadata Url saml_sp_entity_id: anyOf: - type: string - type: 'null' title: Saml Sp Entity Id saml_acs_url: anyOf: - type: string - type: 'null' title: Saml Acs Url oidc_issuer: anyOf: - type: string - type: 'null' title: Oidc Issuer oidc_client_id: anyOf: - type: string - type: 'null' title: Oidc Client Id oidc_client_secret_name: anyOf: - type: string - type: 'null' title: Oidc Client Secret Name description: Secrets vault key name (never stored inline) oidc_scopes: items: type: string type: array title: Oidc Scopes jwt_jwks_url: anyOf: - type: string - type: 'null' title: Jwt Jwks Url jwt_audience: anyOf: - type: string - type: 'null' title: Jwt Audience jwt_issuer: anyOf: - type: string - type: 'null' title: Jwt Issuer api_keys: items: additionalProperties: true type: object type: array title: Api Keys type: object title: AuthConfig description: >- End-user authentication configuration for an App. Supported modes: - ``public``: No authentication required (default) - ``clerk``: Managed auth via Clerk Organizations — handles Google, GitHub, email/password signup/login. Each canvas app maps to a Clerk Organization. Users are synced to canvas_users via Clerk webhooks. - ``password``: Simple password gate — visitors must enter a password to access the app. The password is hashed (bcrypt) before storage. - ``api_key``, ``jwt``, ``sso_oidc``, ``sso_saml``: Advanced modes retained for future use. VersionRecord: properties: version: anyOf: - type: integer - type: 'null' title: Version s3_version_id: anyOf: - type: string - type: 'null' title: S3 Version Id description: S3 object VersionId for instant rollback asset_prefix: anyOf: - type: string - type: 'null' title: Asset Prefix description: S3 asset prefix for this version asset_manifest: anyOf: - additionalProperties: true type: object - type: 'null' title: Asset Manifest description: Map of relative path → {s3_key, hash, size} asset_manifest_url: anyOf: - type: string - type: 'null' title: Asset Manifest Url description: S3 URL of the asset manifest for this version deployed_by: anyOf: - type: string - type: 'null' title: Deployed By deployed_at: anyOf: - type: string format: date-time - type: 'null' title: Deployed At environment: type: string title: Environment default: production build_duration_ms: anyOf: - type: integer - type: 'null' title: Build Duration Ms message: anyOf: - type: string - type: 'null' title: Message source_files: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Source Files description: Map of relative path → file content for source-level version diffs git_commit_sha: anyOf: - type: string - type: 'null' title: Git Commit Sha description: Git commit SHA that triggered this deploy git_commit_message: anyOf: - type: string - type: 'null' title: Git Commit Message description: Git commit message git_author: anyOf: - type: string - type: 'null' title: Git Author description: Git commit author (name ) type: object title: VersionRecord description: A single entry in the App version history. FeaturedGalleryConfig-Output: properties: enabled: type: boolean title: Enabled description: Whether the featured gallery is shown default: true title: type: string title: Title description: Gallery section title default: Featured retriever_id: anyOf: - type: string - type: 'null' title: Retriever Id description: Internal retriever ID (defaults to first tab's retriever) public_name: anyOf: - type: string - type: 'null' title: Public Name description: Marketplace catalog public_name for gallery execution default_inputs: additionalProperties: true type: object title: Default Inputs description: Default inputs to auto-execute when page loads layout: $ref: '#/components/schemas/LayoutConfig' description: Layout configuration for gallery results field_config: additionalProperties: $ref: '#/components/schemas/FieldConfig' type: object title: Field Config description: Field display configuration for gallery results type: object title: FeaturedGalleryConfig description: Configuration for the featured gallery section. PageTab-Output: properties: tab_id: type: string title: Tab Id description: Unique identifier for this tab label: type: string title: Label description: Display label for the tab retriever_id: anyOf: - type: string - type: 'null' title: Retriever Id description: Internal retriever ID (use for private retrievers) public_name: anyOf: - type: string - type: 'null' title: Public Name description: Marketplace catalog public_name (proxies execution via public API) description: anyOf: - type: string - type: 'null' title: Description description: Optional tab description shown as subtitle display_config: $ref: '#/components/schemas/DisplayConfig-Output' description: Display configuration for this tab's search UI type: object required: - tab_id - label - display_config title: PageTab description: A single tab in a Page. 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. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError StructuredDataConfig: properties: type: type: string title: Type description: Schema.org type for structured data default: WebApplication examples: - WebApplication - SearchAction - WebPage - SoftwareApplication additional_properties: additionalProperties: true type: object title: Additional Properties description: Additional Schema.org properties examples: - applicationCategory: Search operatingSystem: Web - potentialAction: '@type': SearchAction target: '{search_term}' type: object title: StructuredDataConfig description: >- Schema.org structured data configuration for search engines. Enables rich search results and better understanding of the page content. LayoutConfig: properties: mode: type: string title: Mode description: Display mode for results default: grid examples: - grid - list - masonry columns: type: integer maximum: 6 minimum: 1 title: Columns description: Number of columns for grid/masonry layouts default: 3 gap: type: string title: Gap description: Gap between items default: 16px examples: - 8px - 16px - 24px full_width: type: boolean title: Full Width description: Whether to use full viewport width for the layout (edge-to-edge) default: false type: object title: LayoutConfig description: Layout configuration for search results display. FieldConfig: properties: format: $ref: '#/components/schemas/FieldFormatType' description: Format type for this field (text, image, date, number, etc.) format_options: $ref: '#/components/schemas/FieldFormatOptions' description: Format-specific display options type: object required: - format title: FieldConfig description: Configuration for how to display a specific field in results. examples: - format: text format_options: label: Title truncate_chars: 60 - format: image format_options: aspect_ratio: 16/9 height: 300 lazy_load: true width: 400 - format: date format_options: date_format: relative label: Posted - format: number format_options: decimals: 2 label: Price prefix: $ DisplayConfig-Input: properties: title: type: string title: Title description: Title/heading for the public search page examples: - Product Search - Video Library - Creative Assets description: anyOf: - type: string - type: 'null' title: Description description: Optional description/subtitle for the page examples: - Search through thousands of products - Find the perfect video clip logo_url: anyOf: - type: string - type: 'null' title: Logo Url description: URL to logo image examples: - https://example.com/logo.png icon_base64: anyOf: - type: string maxLength: 300000 - type: 'null' title: Icon Base64 description: >- Base64 encoded icon/favicon (data URI format recommended). Max size: ~200KB encoded. Use for small icons that should be embedded. Example: 'data:image/png;base64,iVBORw0KGgo...' examples: - data:image/png;base64,iVBORw0KGgoAAAANS... seo: anyOf: - $ref: '#/components/schemas/SEOConfig' - type: 'null' description: >- SEO configuration for search engine and social media discoverability. Auto-generated during publishing with sensible defaults inferred from title, description, and retriever metadata. All fields can be overridden. markdowns: items: $ref: '#/components/schemas/MarkdownContent' type: array title: Markdowns description: >- 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. theme: $ref: '#/components/schemas/ThemeConfig' description: Theme/styling configuration inputs: items: $ref: '#/components/schemas/InputRenderingConfig-Input' type: array title: Inputs description: >- 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. layout: $ref: '#/components/schemas/LayoutConfig' description: Layout configuration for results exposed_fields: items: type: string type: array minItems: 1 title: Exposed Fields description: >- List of document metadata fields to show in results. Only these fields are returned to end users. components: $ref: '#/components/schemas/ComponentsConfig' description: >- Configuration for UI components including search inputs, filters, and result card display options. field_config: additionalProperties: $ref: '#/components/schemas/FieldConfig' type: object title: Field Config description: >- 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. examples: - created_at: format: date format_options: date_format: relative label: Posted price: format: number format_options: decimals: 2 label: Price prefix: $ thumbnail_url: format: image format_options: aspect_ratio: 16/9 height: 300 width: 400 title: format: text format_options: label: Title truncate_chars: 60 custom_cta: anyOf: - $ref: '#/components/schemas/CustomCTA' - type: 'null' description: >- Optional custom call-to-action button displayed in the header bar. Opens a markdown modal when clicked. external_links: items: $ref: '#/components/schemas/ExternalLink' type: array title: External Links description: >- External resource links for this retriever (GitHub repos, blog posts, docs, etc.). Displayed on homepage and retriever listing pages to provide additional context. examples: - - name: GitHub Repository url: https://github.com/org/repo - name: Blog Post url: https://blog.example.com/post template_type: anyOf: - type: string - type: 'null' title: Template Type description: >- Template identifier for frontend rendering. Built-in templates: portrait-gallery, media-search, document-search. Custom templates can use any string identifier. examples: - portrait-gallery - media-search - document-search field_mappings: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Field Mappings description: >- Field mappings from collection output fields to template display slots. Maps template slot names (e.g., 'thumbnail', 'title') to actual field names in the search results. examples: - boundingBox: ocr_bbox extractedText: ocr_text thumbnail: page_thumbnail_url title: document_title extensions: anyOf: - additionalProperties: true type: object - type: 'null' title: Extensions description: >- Generic extensions for template-specific configuration. Allows templates to store custom config without schema changes. examples: - show_timestamps: true video_autoplay: true - bbox_highlight_color: '#FF0000' show_confidence_badge: true retriever_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Retriever Config description: >- Embedded retriever configuration (stages, feature extractors) for the View Config modal. Auto-populated at publish time. additionalProperties: true type: object required: - title - inputs - exposed_fields title: DisplayConfig description: |- Display configuration for public retriever UI. This model defines how the public search interface should be rendered, including input fields, theme, layout, and result card configuration. The frontend (mxp.co) uses this to dynamically build the UI without hardcoded components. examples: - 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 - Use quotes for exact phrases - 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 Our search uses **machine learning** to understand your queries and find the most relevant products. ## Features - **Semantic Search**: Understands meaning, not just keywords - **Visual Search**: Upload images to find similar products - **Smart Filters**: Automatically suggests relevant filters title: How it Works - content: >- ## Tips for Better Results 1. Use descriptive terms (e.g., "wireless noise-canceling headphones") 2. Try different keywords if you don't find what you're looking for 3. Use filters to narrow down results *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 DisplayConfig-Output: properties: title: type: string title: Title description: Title/heading for the public search page examples: - Product Search - Video Library - Creative Assets description: anyOf: - type: string - type: 'null' title: Description description: Optional description/subtitle for the page examples: - Search through thousands of products - Find the perfect video clip logo_url: anyOf: - type: string - type: 'null' title: Logo Url description: URL to logo image examples: - https://example.com/logo.png icon_base64: anyOf: - type: string maxLength: 300000 - type: 'null' title: Icon Base64 description: >- Base64 encoded icon/favicon (data URI format recommended). Max size: ~200KB encoded. Use for small icons that should be embedded. Example: 'data:image/png;base64,iVBORw0KGgo...' examples: - data:image/png;base64,iVBORw0KGgoAAAANS... seo: anyOf: - $ref: '#/components/schemas/SEOConfig' - type: 'null' description: >- SEO configuration for search engine and social media discoverability. Auto-generated during publishing with sensible defaults inferred from title, description, and retriever metadata. All fields can be overridden. markdowns: items: $ref: '#/components/schemas/MarkdownContent' type: array title: Markdowns description: >- 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. theme: $ref: '#/components/schemas/ThemeConfig' description: Theme/styling configuration inputs: items: $ref: '#/components/schemas/InputRenderingConfig-Output' type: array title: Inputs description: >- 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. layout: $ref: '#/components/schemas/LayoutConfig' description: Layout configuration for results exposed_fields: items: type: string type: array minItems: 1 title: Exposed Fields description: >- List of document metadata fields to show in results. Only these fields are returned to end users. components: $ref: '#/components/schemas/ComponentsConfig' description: >- Configuration for UI components including search inputs, filters, and result card display options. field_config: additionalProperties: $ref: '#/components/schemas/FieldConfig' type: object title: Field Config description: >- 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. examples: - created_at: format: date format_options: date_format: relative label: Posted price: format: number format_options: decimals: 2 label: Price prefix: $ thumbnail_url: format: image format_options: aspect_ratio: 16/9 height: 300 width: 400 title: format: text format_options: label: Title truncate_chars: 60 custom_cta: anyOf: - $ref: '#/components/schemas/CustomCTA' - type: 'null' description: >- Optional custom call-to-action button displayed in the header bar. Opens a markdown modal when clicked. external_links: items: $ref: '#/components/schemas/ExternalLink' type: array title: External Links description: >- External resource links for this retriever (GitHub repos, blog posts, docs, etc.). Displayed on homepage and retriever listing pages to provide additional context. examples: - - name: GitHub Repository url: https://github.com/org/repo - name: Blog Post url: https://blog.example.com/post template_type: anyOf: - type: string - type: 'null' title: Template Type description: >- Template identifier for frontend rendering. Built-in templates: portrait-gallery, media-search, document-search. Custom templates can use any string identifier. examples: - portrait-gallery - media-search - document-search field_mappings: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Field Mappings description: >- Field mappings from collection output fields to template display slots. Maps template slot names (e.g., 'thumbnail', 'title') to actual field names in the search results. examples: - boundingBox: ocr_bbox extractedText: ocr_text thumbnail: page_thumbnail_url title: document_title extensions: anyOf: - additionalProperties: true type: object - type: 'null' title: Extensions description: >- Generic extensions for template-specific configuration. Allows templates to store custom config without schema changes. examples: - show_timestamps: true video_autoplay: true - bbox_highlight_color: '#FF0000' show_confidence_badge: true retriever_config: anyOf: - additionalProperties: true type: object - type: 'null' title: Retriever Config description: >- Embedded retriever configuration (stages, feature extractors) for the View Config modal. Auto-populated at publish time. additionalProperties: true type: object required: - title - inputs - exposed_fields title: DisplayConfig description: |- Display configuration for public retriever UI. This model defines how the public search interface should be rendered, including input fields, theme, layout, and result card configuration. The frontend (mxp.co) uses this to dynamically build the UI without hardcoded components. examples: - 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 - Use quotes for exact phrases - 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 Our search uses **machine learning** to understand your queries and find the most relevant products. ## Features - **Semantic Search**: Understands meaning, not just keywords - **Visual Search**: Upload images to find similar products - **Smart Filters**: Automatically suggests relevant filters title: How it Works - content: >- ## Tips for Better Results 1. Use descriptive terms (e.g., "wireless noise-canceling headphones") 2. Try different keywords if you don't find what you're looking for 3. Use filters to narrow down results *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 FieldFormatType: type: string enum: - text - image - date - number - url - boolean - array - object title: FieldFormatType description: Supported field format types for result display. FieldFormatOptions: properties: label: anyOf: - type: string - type: 'null' title: Label description: Display label for this field examples: - Title - Price - Posted Date show_empty: type: boolean title: Show Empty description: Whether to show the field if value is empty/null default: true truncate_chars: anyOf: - type: integer minimum: 1 - type: 'null' title: Truncate Chars description: Maximum characters before truncation (for text fields) examples: - 60 - 120 - 200 width: anyOf: - type: integer minimum: 1 - type: 'null' title: Width description: Image width in pixels examples: - 400 - 800 height: anyOf: - type: integer minimum: 1 - type: 'null' title: Height description: Image height in pixels examples: - 300 - 600 lazy_load: type: boolean title: Lazy Load description: 'Enable lazy loading for images (default: true)' default: true aspect_ratio: anyOf: - type: string - type: 'null' title: Aspect Ratio description: Aspect ratio for image container examples: - 16/9 - 4/3 - 1/1 object_fit: type: string title: Object Fit description: CSS object-fit property for images default: cover examples: - cover - contain - fill date_format: type: string title: Date Format description: 'Date format type: ''iso'', ''relative'', or custom format string' default: relative examples: - relative - iso - MMM DD, YYYY decimals: anyOf: - type: integer minimum: 0 - type: 'null' title: Decimals description: Number of decimal places examples: - 0 - 1 - 2 prefix: anyOf: - type: string - type: 'null' title: Prefix description: Prefix for number display examples: - $ - € - '#' suffix: anyOf: - type: string - type: 'null' title: Suffix description: Suffix for number display examples: - '%' - k - M open_in_new_tab: type: boolean title: Open In New Tab description: 'Open URLs in new tab (default: true)' default: true show_domain: type: boolean title: Show Domain description: Show domain instead of full URL default: false true_label: type: string title: True Label description: Label for true values default: 'Yes' false_label: type: string title: False Label description: Label for false values default: 'No' separator: type: string title: Separator description: 'Separator for array items (default: '', '')' default: ', ' max_items: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Items description: Maximum array items to display type: object title: FieldFormatOptions description: |- Format-specific options for field display. Different format types support different options: - text: label, truncate_chars, show_empty - image: width, height, lazy_load, aspect_ratio, object_fit - date: label, date_format (iso, relative, custom) - number: label, decimals, prefix, suffix, show_empty - url: label, open_in_new_tab, show_domain - boolean: label, true_label, false_label - array: label, separator, max_items examples: - label: Title show_empty: false truncate_chars: 60 - aspect_ratio: 16/9 height: 300 label: Thumbnail lazy_load: true object_fit: cover width: 400 - date_format: relative label: Posted - decimals: 2 label: Price prefix: $ MarkdownContent: properties: title: type: string maxLength: 200 minLength: 1 title: Title description: Title for the markdown content section examples: - How it Works - Getting Started - About This Search - Search Tips content: type: string maxLength: 50000 minLength: 1 title: Content description: >- Markdown-formatted content. Supports standard markdown syntax including headers, lists, links, images, code blocks, and emphasis. Limited to 50KB to prevent database issues. examples: - |- # Welcome This search uses **AI** to understand your queries. - |- ## Features - Semantic search - Multi-modal - Fast results - |- ### Tips 1. Use specific terms 2. Try multiple queries [Learn more](https://docs.example.com) type: object required: - title - content title: MarkdownContent description: |- Reusable markdown content model with title and content. This model provides a structured way to include rich markdown content anywhere in the published retriever configuration. Includes safety constraints to prevent database issues. InputRenderingConfig-Input: properties: field_name: type: string title: Field Name description: Name of the input field (matches retriever input_schema key) examples: - query - image_url - video_url - category field_schema: $ref: '#/components/schemas/RetrieverInputSchemaField-Input' description: >- Schema definition for this input field. Defines type, description, examples, and validation rules. Supports all bucket types (string, number, image, etc.) plus document_reference. Frontend uses this to render the appropriate input component (text input, image upload, dropdown, etc.) input_type: type: string title: Input Type description: >- UI input component type. Determines how the input is rendered: text (single line), select (dropdown), file (upload), multiselect (multiple choice) default: text examples: - text - select - file - multiselect label: type: string title: Label description: Human-readable label for the input examples: - Search Query - Upload Image - Select Category placeholder: anyOf: - type: string - type: 'null' title: Placeholder description: Placeholder text for the input examples: - Enter search terms... - Drag and drop or click to upload helper_text: anyOf: - type: string - type: 'null' title: Helper Text description: Helper text displayed below the input to guide users examples: - Describe the aesthetic, outfit, or vibe you're looking for - Enter keywords separated by commas - Use natural language to describe what you're searching for suggestions: anyOf: - items: type: string type: array - type: 'null' title: Suggestions description: >- Pre-filled suggestion chips that users can click to populate the input examples: - - streetwear urban - clean girl minimal - summer haul bright - - wireless headphones - laptop under $1000 - gaming mouse - - minimalist - oversized hoodie - aesthetic vibe required: type: boolean title: Required description: Whether this input is required default: true order: type: integer minimum: 0 title: Order description: Display order (lower numbers appear first) default: 0 type: object required: - field_name - field_schema - label title: InputRenderingConfig description: |- Configuration for how to render an input field in the public UI. Maps to BucketSchemaField structure for consistency with how we define input types across the system. examples: - field_name: query field_schema: description: Text search query examples: - red sports car - sunset over ocean type: string helper_text: Describe the aesthetic, outfit, or vibe you're looking for label: Search by style order: 0 placeholder: 'Try: oversized hoodie streetwear urban' required: true suggestions: - streetwear urban - clean girl minimal - summer haul bright - minimalist aesthetic - field_name: image_url field_schema: description: Image for visual search examples: - https://example.com/image.jpg type: image helper_text: Upload an image to find visually similar items label: Upload Image order: 1 placeholder: Drop image or paste URL required: false ComponentsConfig: properties: show_hero: type: boolean title: Show Hero description: Whether to show the hero section with title and description default: true show_search: type: boolean title: Show Search description: Whether to show search input fields default: true show_filters: type: boolean title: Show Filters description: Whether to show filters sidebar default: false show_results_header: type: boolean title: Show Results Header description: Whether to show the results header with count and sorting options default: true result_layout: type: string title: Result Layout description: Layout mode for results display default: grid examples: - grid - list - masonry result_card: anyOf: - $ref: '#/components/schemas/ResultCardProperties' - type: 'null' description: Configuration for result card display type: object title: ComponentsConfig description: Configuration for UI components. examples: - result_card: card_click_action: viewDetails field_order: - title - description layout: vertical show_find_similar: true show_thumbnail: true result_layout: grid show_filters: false show_hero: true show_results_header: true show_search: true CustomCTA: properties: label: type: string maxLength: 50 minLength: 1 title: Label description: Button label text displayed in the header examples: - How to Use - Search Tips - About - Help markdown_content: type: string maxLength: 50000 minLength: 1 title: Markdown Content description: >- Markdown content displayed in the modal when button is clicked. Supports standard markdown syntax. examples: - |- # Getting Started This search engine allows you to... ## Tips - Use specific keywords - Try different queries type: object required: - label - markdown_content title: CustomCTA description: |- Optional custom button in header that opens a markdown modal. Allows users to add a custom call-to-action button in the header bar that opens a modal with markdown content when clicked. examples: - label: Search Tips markdown_content: |- # Search Tips - Use quotes for exact phrases - Filter by date using 'after:2024' ExternalLink: properties: name: type: string maxLength: 100 minLength: 1 title: Name description: Display name for the link examples: - GitHub Repository - Blog Post - Documentation - Demo Video url: type: string maxLength: 2048 minLength: 1 title: Url description: URL to the external resource examples: - https://github.com/org/repo - https://blog.example.com/post - https://docs.example.com type: object required: - name - url title: ExternalLink description: |- External resource link for a published retriever. Used to link to related resources like GitHub repos, blog posts, documentation, or other relevant URLs displayed on the homepage. examples: - name: GitHub Repository url: https://github.com/mixpeek/video-search - name: Blog Post url: https://blog.mixpeek.com/building-semantic-search InputRenderingConfig-Output: properties: field_name: type: string title: Field Name description: Name of the input field (matches retriever input_schema key) examples: - query - image_url - video_url - category field_schema: $ref: '#/components/schemas/RetrieverInputSchemaField-Output' description: >- Schema definition for this input field. Defines type, description, examples, and validation rules. Supports all bucket types (string, number, image, etc.) plus document_reference. Frontend uses this to render the appropriate input component (text input, image upload, dropdown, etc.) input_type: type: string title: Input Type description: >- UI input component type. Determines how the input is rendered: text (single line), select (dropdown), file (upload), multiselect (multiple choice) default: text examples: - text - select - file - multiselect label: type: string title: Label description: Human-readable label for the input examples: - Search Query - Upload Image - Select Category placeholder: anyOf: - type: string - type: 'null' title: Placeholder description: Placeholder text for the input examples: - Enter search terms... - Drag and drop or click to upload helper_text: anyOf: - type: string - type: 'null' title: Helper Text description: Helper text displayed below the input to guide users examples: - Describe the aesthetic, outfit, or vibe you're looking for - Enter keywords separated by commas - Use natural language to describe what you're searching for suggestions: anyOf: - items: type: string type: array - type: 'null' title: Suggestions description: >- Pre-filled suggestion chips that users can click to populate the input examples: - - streetwear urban - clean girl minimal - summer haul bright - - wireless headphones - laptop under $1000 - gaming mouse - - minimalist - oversized hoodie - aesthetic vibe required: type: boolean title: Required description: Whether this input is required default: true order: type: integer minimum: 0 title: Order description: Display order (lower numbers appear first) default: 0 type: object required: - field_name - field_schema - label title: InputRenderingConfig description: |- Configuration for how to render an input field in the public UI. Maps to BucketSchemaField structure for consistency with how we define input types across the system. examples: - field_name: query field_schema: description: Text search query examples: - red sports car - sunset over ocean type: string helper_text: Describe the aesthetic, outfit, or vibe you're looking for label: Search by style order: 0 placeholder: 'Try: oversized hoodie streetwear urban' required: true suggestions: - streetwear urban - clean girl minimal - summer haul bright - minimalist aesthetic - field_name: image_url field_schema: description: Image for visual search examples: - https://example.com/image.jpg type: image helper_text: Upload an image to find visually similar items label: Upload Image order: 1 placeholder: Drop image or paste URL required: false RetrieverInputSchemaField-Input: properties: type: $ref: '#/components/schemas/RetrieverInputSchemaFieldType' default: anyOf: - {} - type: 'null' title: Default items: anyOf: - $ref: '#/components/schemas/RetrieverInputSchemaField-Input' - type: 'null' properties: anyOf: - additionalProperties: $ref: '#/components/schemas/RetrieverInputSchemaField-Input' type: object - type: 'null' title: Properties examples: anyOf: - items: {} type: array - type: 'null' title: Examples description: >- OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible. description: anyOf: - type: string - type: 'null' title: Description enum: anyOf: - items: {} type: array - type: 'null' title: Enum required: anyOf: - type: boolean - type: 'null' title: Required default: false additionalProperties: true type: object required: - type title: RetrieverInputSchemaField description: >- Schema field definition for retriever input parameters. Identical structure to BucketSchemaField but uses RetrieverInputSchemaFieldType which includes additional reference types like document_reference. This allows retrievers to accept: 1. Metadata inputs (strings, numbers, dates, etc.) 2. File inputs (images, videos, documents for search) 3. Reference inputs (document_reference for "find similar" queries) ResultCardProperties: properties: layout: type: string title: Layout description: Card layout orientation default: vertical examples: - vertical - horizontal show_thumbnail: type: boolean title: Show Thumbnail description: Whether to show thumbnail image in results default: true thumbnail_aspect_ratio: type: string title: Thumbnail Aspect Ratio description: Aspect ratio for thumbnail images default: 16/9 examples: - 16/9 - 4/3 - 1/1 thumbnail_fit: type: string title: Thumbnail Fit description: How thumbnail should fit in container default: cover examples: - cover - contain show_score: type: boolean title: Show Score description: Whether to display relevance score default: false truncate_title: anyOf: - type: integer minimum: 1 - type: 'null' title: Truncate Title description: Maximum characters for title before truncation examples: - 60 - 80 - 100 truncate_description: anyOf: - type: integer minimum: 1 - type: 'null' title: Truncate Description description: Maximum characters for description before truncation examples: - 120 - 150 - 200 field_order: items: type: string type: array title: Field Order description: >- Order of fields to display in result card. Fields not in this list won't be shown. Must be subset of exposed_fields. examples: - - title - description - category - created_at - - thumbnail_url - title - price - views show_find_similar: type: boolean title: Show Find Similar description: Whether to show a 'Find Similar' button on result cards default: false card_click_action: type: string title: Card Click Action description: >- Action when card is clicked: none (no action), findSimilar (trigger similar search), viewDetails (open detail modal) default: viewDetails examples: - none - findSimilar - viewDetails thumbnail_field: anyOf: - type: string - type: 'null' title: Thumbnail Field description: Field name to use as thumbnail image source examples: - thumbnail_url - image_url - page_image title_field: anyOf: - type: string - type: 'null' title: Title Field description: Field name to use as card title examples: - title - name - document_title card_fields: anyOf: - items: type: string type: array - type: 'null' title: Card Fields description: >- Fields to display on the card (alternative to field_order for template compatibility) examples: - - title - description - price modal_fields: anyOf: - items: type: string type: array - type: 'null' title: Modal Fields description: Fields to display in the detail modal when card is clicked examples: - - title - description - full_text - metadata card_style: anyOf: - type: string - type: 'null' title: Card Style description: >- Card style preset: default, portrait-discovery, media-search, document-search, or custom template-specific styles default: default examples: - default - portrait-discovery - media-search - document-search type: object title: ResultCardProperties description: Properties for result card display configuration. examples: - card_click_action: viewDetails card_style: default field_order: - title - description - category - created_at layout: vertical show_find_similar: true show_score: true show_thumbnail: true thumbnail_aspect_ratio: 16/9 thumbnail_field: image_url thumbnail_fit: cover title_field: title truncate_description: 120 truncate_title: 60 RetrieverInputSchemaField-Output: properties: type: $ref: '#/components/schemas/RetrieverInputSchemaFieldType' default: anyOf: - {} - type: 'null' title: Default items: anyOf: - $ref: '#/components/schemas/RetrieverInputSchemaField-Output' - type: 'null' properties: anyOf: - additionalProperties: $ref: '#/components/schemas/RetrieverInputSchemaField-Output' type: object - type: 'null' title: Properties examples: anyOf: - items: {} type: array - type: 'null' title: Examples description: >- OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible. description: anyOf: - type: string - type: 'null' title: Description enum: anyOf: - items: {} type: array - type: 'null' title: Enum required: anyOf: - type: boolean - type: 'null' title: Required default: false additionalProperties: true type: object required: - type title: RetrieverInputSchemaField description: >- Schema field definition for retriever input parameters. Identical structure to BucketSchemaField but uses RetrieverInputSchemaFieldType which includes additional reference types like document_reference. This allows retrievers to accept: 1. Metadata inputs (strings, numbers, dates, etc.) 2. File inputs (images, videos, documents for search) 3. Reference inputs (document_reference for "find similar" queries) RetrieverInputSchemaFieldType: type: string enum: - string - number - integer - float - boolean - object - array - date - datetime - text - image - audio - video - pdf - excel - document_reference title: RetrieverInputSchemaFieldType description: >- Supported data types for retriever input schema fields. Retriever input schemas define what parameters users can provide when executing a retriever. This includes all bucket schema types plus additional reference types. Types fall into three categories: 1. **Metadata Types** (JSON types): - Standard JSON-compatible types - Examples: string, number, boolean, date - Inherited from BucketSchemaFieldType 2. **File Types** (blobs): - Users can upload files/content as search inputs - Examples: text, image, video, pdf - Inherited from BucketSchemaFieldType 3. **Reference Types** (structured metadata): - Special types for referencing existing documents - Examples: document_reference - Only available in retriever input schemas (NOT in bucket schemas) **DOCUMENT_REFERENCE Usage**: Accept document reference for "find similar" queries. Example - Find similar products retriever: { "reference_product": { "type": "document_reference", "description": "Find products similar to this one", "required": true } } Execution input: { "inputs": { "reference_product": { "collection_id": "col_products", "document_id": "doc_item_123" } } } The system will use the pre-computed features from doc_item_123 to find similar documents without re-processing. ````