---
title: "Create an App"
method: POST
path: "/v1/apps"
tags: ["Apps"]
---

# Create an App

`POST /v1/apps`

Create a new App.

Apps are full-stack web applications deployed as zip bundles to
``{slug}.mxp.co``.  After creation, deploy your built frontend via the
deploy pipeline:

1. ``POST /v1/apps/{app_id}/deploy/upload-url`` — get a presigned S3 PUT URL
2. Upload your built ``dist/`` zip to that URL
3. ``POST /v1/apps/{app_id}/deploy`` — trigger the build

Only ``slug`` and ``meta`` are required.  Set ``auth_config.mode`` to
control end-user authentication (``public``, ``clerk``, ``password``,
``api_key``, ``jwt``, ``sso_oidc``, ``sso_saml``).

Slugs are globally unique across all organizations.

**Deprecated fields:** ``template``, ``sections``, ``custom_html``,
``hero``, ``theme``, ``seo``, ``stats``, ``featured_gallery``, ``tabs``,
``password_secret_name`` are accepted for backward compatibility but
should not be used for new apps.

**Tier limits:** Free = 1 app, Pro = 10, Enterprise = unlimited
(``TierLimits._max_apps``). Exceeding your tier's limit returns a 400 with
the limit + current count in ``error.details``.

## Request body

- CreateAppRequest — Request to create a new App. Only ``slug`` and ``meta`` are required. After creation, deploy a zip bundle via ``POST /v1/apps/{app_id}/deploy``. Legacy page-builder fields (``template``, ``sections``, ``custom_html``, ``hero``, ``theme``, ``seo``, ``stats``, ``featured_gallery``, ``tabs``, ``password_secret_name``) are accepted for backward compatibility but **deprecated**. New apps should not use them.
  - `slug` string, required — URL-safe slug (globally unique, lowercase + hyphens). Becomes your URL: {slug}.mxp.co
  - `meta` PageMeta, required — 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.).
    - `title` string, required — Page title displayed in the browser tab and page header.
    - `description` string, nullable — Short page description shown in the page header or subtitle area.
    - `logo_url` string, nullable — URL of the logo displayed in the page header.
    - `favicon_url` string, nullable — URL of the favicon for the browser tab.
    - `indexable` boolean, nullable — 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.
  - `auth_config` AuthConfigInput — 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.
    - `mode` 'public' | 'clerk' | 'password' | 'api_key' | 'jwt' | 'sso_oidc' | 'sso_saml' — Authentication mode
    - `clerk_org_id` string, nullable — Clerk Organization ID for this app (auto-provisioned)
    - `clerk_allowed_providers` string[] — Enabled auth providers: google, github, email
    - `password` string, nullable — Plaintext password (write-only — hashed before storage, never returned in responses)
    - `password_hash` string, nullable — Bcrypt hash of the password (internal — never exposed in API responses)
    - `saml_idp_metadata_url` string, nullable
    - `saml_sp_entity_id` string, nullable
    - `saml_acs_url` string, nullable
    - `oidc_issuer` string, nullable
    - `oidc_client_id` string, nullable
    - `oidc_client_secret_name` string, nullable — Secrets vault key name (never stored inline)
    - `oidc_scopes` string[]
    - `jwt_jwks_url` string, nullable
    - `jwt_audience` string, nullable
    - `jwt_issuer` string, nullable
    - `api_keys` object[]
  - `build_config` BuildConfig — JSX build configuration for an App. Phase 1: schema only. Phase 3: used by the build pipeline Celery task.
    - `entry` string — Build entry point
    - `framework` 'react'
    - `tailwind` boolean
    - `env_vars` object — 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` object — 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` string, nullable — CDN asset prefix once deployed
  - `monitoring_config` MonitoringConfig — 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.
    - `enabled` boolean — Master switch — must be true for any monitoring to activate
    - `error_boundary_enabled` boolean — 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.
    - `sentry_enabled` boolean — Capture unhandled exceptions to Mixpeek-internal Sentry. No PII is captured (beforeSend strips it).
    - `posthog_enabled` boolean — Capture pageviews and error counts to Mixpeek-internal PostHog. No text content, no session recordings.
    - `custom_error_message` string, nullable — Custom message shown in the Error Boundary fallback UI
    - `auto_fix_enabled` boolean — When true, error spikes trigger the Claude-powered auto-fix pipeline. Requires source_files on the latest version or a connected GitHub repo.
  - `is_active` boolean
  - `template` string
  - `sections` SectionConfig[]
    - `section_id` string — Auto-generated section identifier
    - `type` string, required — Section type: 'hero', 'stats-bar', 'featured-gallery', 'search-tabs', 'results-grid', 'results-list', 'markdown-content', 'iframe-embed'
    - `props` object — Section-specific configuration properties
    - `order` integer, nullable — Explicit render order; falls back to array position if omitted
  - `custom_html` string, nullable
  - `hero` HeroConfig — Hero section configuration for a page.
    - `headline` string, required — Main headline text
    - `subheadline` string, nullable — Optional subheadline text
    - `background_type` 'image' | 'video' | 'gradient' | 'solid' — Background type
    - `background_url` string, nullable — URL for image or video background
    - `background_color` string, nullable — Background color for solid/gradient
    - `text_color` string — Hero text color
    - `logo_url` string, nullable — Logo URL displayed in hero
    - `height` string — Hero section height
    - `cta_label` string, nullable — Call-to-action button label
    - `cta_url` string, nullable — Call-to-action button URL
  - `theme` ThemeConfig — Theme configuration for public retriever UI. Defines colors, fonts, and visual styling for the public search interface.
    - `primary_color` string — Primary brand color (hex code)
    - `secondary_color` string, nullable — Secondary/accent color (hex code)
    - `font_family` string — Font family for text
    - `background_color` string — Background color (hex code)
    - `text_color` string — Primary text color (hex code)
    - `heading_font_family` string, nullable — Optional separate font family for headings
    - `surface_color` string, nullable — Surface/card background color (hex code)
    - `muted_color` string, nullable — Muted/secondary text color (hex code)
    - `border_color` string, nullable — Border color for cards and elements (hex code)
    - `border_radius` string, nullable — Default border radius for cards and elements
    - `card_style` string, nullable — Card visual style: elevated (shadow), flat (no shadow), bordered, or glass (frosted glass effect)
    - `card_hover_effect` string, nullable — Card hover animation effect: lift (move up), glow, scale, or none
  - `seo` SEOConfig — 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
    - `meta_title` string, nullable — SEO-optimized page title (50-60 chars recommended). Auto-generated from display_config.title + site_name if not provided.
    - `meta_description` string, nullable — Meta description for search engine snippets (max 160 chars). Auto-generated from display_config.description if not provided.
    - `keywords` string[] — Relevant keywords for search engines. Auto-inferred from title, description, and retriever tags.
    - `og_image_url` string, nullable — URL to OG image for social previews (1200x630px recommended). Auto-generated and uploaded to public S3 bucket during publishing.
    - `og_image_alt` string, nullable — Alt text for OG image (accessibility and SEO)
    - `og_type` string — Open Graph content type
    - `twitter_card` string — Twitter card display style
    - `twitter_site` string, nullable — Twitter @handle for the site
    - `twitter_creator` string, nullable — Twitter @handle for content creator (optional)
    - `robots` string — Robots meta directive for search engine crawlers. Use 'noindex, nofollow' to hide from search engines.
    - `canonical_url` string, nullable — Canonical URL if different from default. Auto-set to https://mxp.co/r/{public_name} if not provided.
    - `site_name` string — Site name for OG tags and branding
    - `author` string, nullable — Content author/creator name
    - `locale` string — Content language/locale
    - `logo_url` string, nullable — URL to organization/brand logo for SEO and branding. Used in structured data and can be displayed in search results.
    - `favicon_url` string, nullable — URL to favicon/icon for the public retriever page. Recommended sizes: 32x32, 48x48, or 180x180 for Apple touch icon.
    - `structured_data` StructuredDataConfig — Schema.org structured data configuration for search engines. Enables rich search results and better understanding of the page content.
      - `type` string — Schema.org type for structured data
      - `additional_properties` object — Additional Schema.org properties
  - `stats` StatItem[]
    - `label` string, required — Stat label (e.g. 'Total Ads')
    - `value` string, required — Stat value (e.g. '12,400+')
  - `featured_gallery` FeaturedGalleryConfigInput — Configuration for the featured gallery section.
    - `enabled` boolean — Whether the featured gallery is shown
    - `title` string — Gallery section title
    - `retriever_id` string, nullable — Internal retriever ID (defaults to first tab's retriever)
    - `public_name` string, nullable — Marketplace catalog public_name for gallery execution
    - `default_inputs` object — Default inputs to auto-execute when page loads
    - `layout` LayoutConfig — Layout configuration for search results display.
      - `mode` string — Display mode for results
      - `columns` integer — Number of columns for grid/masonry layouts
      - `gap` string — Gap between items
      - `full_width` boolean — Whether to use full viewport width for the layout (edge-to-edge)
    - `field_config` object — Field display configuration for gallery results
  - `tabs` PageTabInput[]
    - `tab_id` string, required — Unique identifier for this tab
    - `label` string, required — Display label for the tab
    - `retriever_id` string, nullable — Internal retriever ID (use for private retrievers)
    - `public_name` string, nullable — Marketplace catalog public_name (proxies execution via public API)
    - `description` string, nullable — Optional tab description shown as subtitle
    - `display_config` DisplayConfigInput, required — 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.
      - `title` string, required — Title/heading for the public search page
      - `description` string, nullable — Optional description/subtitle for the page
      - `logo_url` string, nullable — URL to logo image
      - `icon_base64` string, nullable — 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...'
      - `seo` SEOConfig — 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
        - `meta_title` string, nullable — SEO-optimized page title (50-60 chars recommended). Auto-generated from display_config.title + site_name if not provided.
        - `meta_description` string, nullable — Meta description for search engine snippets (max 160 chars). Auto-generated from display_config.description if not provided.
        - `keywords` string[] — Relevant keywords for search engines. Auto-inferred from title, description, and retriever tags.
        - `og_image_url` string, nullable — URL to OG image for social previews (1200x630px recommended). Auto-generated and uploaded to public S3 bucket during publishing.
        - `og_image_alt` string, nullable — Alt text for OG image (accessibility and SEO)
        - `og_type` string — Open Graph content type
        - `twitter_card` string — Twitter card display style
        - `twitter_site` string, nullable — Twitter @handle for the site
        - `twitter_creator` string, nullable — Twitter @handle for content creator (optional)
        - `robots` string — Robots meta directive for search engine crawlers. Use 'noindex, nofollow' to hide from search engines.
        - `canonical_url` string, nullable — Canonical URL if different from default. Auto-set to https://mxp.co/r/{public_name} if not provided.
        - `site_name` string — Site name for OG tags and branding
        - `author` string, nullable — Content author/creator name
        - `locale` string — Content language/locale
        - `logo_url` string, nullable — URL to organization/brand logo for SEO and branding. Used in structured data and can be displayed in search results.
        - `favicon_url` string, nullable — URL to favicon/icon for the public retriever page. Recommended sizes: 32x32, 48x48, or 180x180 for Apple touch icon.
        - `structured_data` StructuredDataConfig — Schema.org structured data configuration for search engines. Enables rich search results and better understanding of the page content.
          - `type` string — Schema.org type for structured data
          - `additional_properties` object — Additional Schema.org properties
      - `markdowns` MarkdownContent[] — 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.
        - `title` string, required — Title for the markdown content section
        - `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.
      - `theme` ThemeConfig — Theme configuration for public retriever UI. Defines colors, fonts, and visual styling for the public search interface.
        - `primary_color` string — Primary brand color (hex code)
        - `secondary_color` string, nullable — Secondary/accent color (hex code)
        - `font_family` string — Font family for text
        - `background_color` string — Background color (hex code)
        - `text_color` string — Primary text color (hex code)
        - `heading_font_family` string, nullable — Optional separate font family for headings
        - `surface_color` string, nullable — Surface/card background color (hex code)
        - `muted_color` string, nullable — Muted/secondary text color (hex code)
        - `border_color` string, nullable — Border color for cards and elements (hex code)
        - `border_radius` string, nullable — Default border radius for cards and elements
        - `card_style` string, nullable — Card visual style: elevated (shadow), flat (no shadow), bordered, or glass (frosted glass effect)
        - `card_hover_effect` string, nullable — Card hover animation effect: lift (move up), glow, scale, or none
      - `inputs` InputRenderingConfigInput[], 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.
        - `field_name` string, required — Name of the input field (matches retriever input_schema key)
        - `field_schema` RetrieverInputSchemaFieldInput, required — 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)
          - `type` 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'object' | 'array' | 'date' | 'datetime' | 'text' | 'image' | 'audio' | 'video' | 'pdf' | 'excel' | 'document_reference', required — 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.
          - `default` unknown
          - `items` RetrieverInputSchemaFieldInput — recursive
          - `properties` object, nullable
          - `examples` unknown[], nullable — OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible.
            - unknown
          - `description` string, nullable
          - `enum` unknown[], nullable
            - unknown
          - `required` boolean, nullable
        - `input_type` string — UI input component type. Determines how the input is rendered: text (single line), select (dropdown), file (upload), multiselect (multiple choice)
        - `label` string, required — Human-readable label for the input
        - `placeholder` string, nullable — Placeholder text for the input
        - `helper_text` string, nullable — Helper text displayed below the input to guide users
        - `suggestions` string[], nullable — Pre-filled suggestion chips that users can click to populate the input
        - `required` boolean — Whether this input is required
        - `order` integer — Display order (lower numbers appear first)
      - `layout` LayoutConfig — Layout configuration for search results display.
        - `mode` string — Display mode for results
        - `columns` integer — Number of columns for grid/masonry layouts
        - `gap` string — Gap between items
        - `full_width` boolean — Whether to use full viewport width for the layout (edge-to-edge)
      - `exposed_fields` string[], required — List of document metadata fields to show in results. Only these fields are returned to end users.
      - `components` ComponentsConfig — Configuration for UI components.
        - `show_hero` boolean — Whether to show the hero section with title and description
        - `show_search` boolean — Whether to show search input fields
        - `show_filters` boolean — Whether to show filters sidebar
        - `show_results_header` boolean — Whether to show the results header with count and sorting options
        - `result_layout` string — Layout mode for results display
        - `result_card` ResultCardProperties — Properties for result card display configuration.
          - `layout` string — Card layout orientation
          - `show_thumbnail` boolean — Whether to show thumbnail image in results
          - `thumbnail_aspect_ratio` string — Aspect ratio for thumbnail images
          - `thumbnail_fit` string — How thumbnail should fit in container
          - `show_score` boolean — Whether to display relevance score
          - `truncate_title` integer, nullable — Maximum characters for title before truncation
          - `truncate_description` integer, nullable — Maximum characters for description before truncation
          - `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.
          - `show_find_similar` boolean — Whether to show a 'Find Similar' button on result cards
          - `card_click_action` string — Action when card is clicked: none (no action), findSimilar (trigger similar search), viewDetails (open detail modal)
          - `thumbnail_field` string, nullable — Field name to use as thumbnail image source
          - `title_field` string, nullable — Field name to use as card title
          - `card_fields` string[], nullable — Fields to display on the card (alternative to field_order for template compatibility)
          - `modal_fields` string[], nullable — Fields to display in the detail modal when card is clicked
          - `card_style` string, nullable — Card style preset: default, portrait-discovery, media-search, document-search, or custom template-specific styles
      - `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.
      - `custom_cta` CustomCTA — 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.
        - `label` string, required — Button label text displayed in the header
        - `markdown_content` string, required — Markdown content displayed in the modal when button is clicked. Supports standard markdown syntax.
      - `external_links` ExternalLink[] — External resource links for this retriever (GitHub repos, blog posts, docs, etc.). Displayed on homepage and retriever listing pages to provide additional context.
        - `name` string, required — Display name for the link
        - `url` string, required — URL to the external resource
      - `template_type` string, nullable — Template identifier for frontend rendering. Built-in templates: portrait-gallery, media-search, document-search. Custom templates can use any string identifier.
      - `field_mappings` object, nullable — 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.
      - `extensions` object, nullable — Generic extensions for template-specific configuration. Allows templates to store custom config without schema changes.
      - `retriever_config` object, nullable — Embedded retriever configuration (stages, feature extractors) for the View Config modal. Auto-populated at publish time.
  - `password_secret_name` string, nullable

## Response `200`

The created App configuration

- AppResponse — 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**.
  - `app_id` string, required
  - `slug` string, required
  - `url` string, required — Canonical published URL (https://{slug}.mxp.co)
  - `meta` PageMeta, required — 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.).
    - `title` string, required — Page title displayed in the browser tab and page header.
    - `description` string, nullable — Short page description shown in the page header or subtitle area.
    - `logo_url` string, nullable — URL of the logo displayed in the page header.
    - `favicon_url` string, nullable — URL of the favicon for the browser tab.
    - `indexable` boolean, nullable — 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.
  - `is_active` boolean, required
  - `warnings` string[] — Non-fatal advisories about the request that was just applied. Currently used to spell out the effect of a takedown write, e.g. 'is_active: false' makes the canvas runtime refuse the app's URL with a 404 within its serving-cache window, and the note says how to verify that. Additive and safe to ignore.
  - `version` integer, required
  - `has_unpublished_changes` boolean
  - `custom_domains` CustomDomainConfig[], required
    - `domain` string, required — Customer domain (e.g. 'search.acme.com')
    - `status` 'pending' | 'verifying' | 'provisioning_tls' | 'active' — Domain verification and TLS lifecycle state
    - `verification_token` string, nullable — TXT record value for DNS ownership verification
    - `cname_target` string, nullable — CNAME target (e.g. '{slug}.mxp.co')
    - `tls_cert_id` string, nullable — TLS certificate reference
    - `tls_expires_at` string, date-time, nullable — TLS cert expiry
    - `verified_at` string, date-time, nullable — When domain was verified
    - `is_primary` boolean — Whether this is the primary domain
  - `auth_config` AuthConfigOutput, required — 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.
    - `mode` 'public' | 'clerk' | 'password' | 'api_key' | 'jwt' | 'sso_oidc' | 'sso_saml' — Authentication mode
    - `clerk_org_id` string, nullable — Clerk Organization ID for this app (auto-provisioned)
    - `clerk_allowed_providers` string[] — Enabled auth providers: google, github, email
    - `password_hash` string, nullable — Bcrypt hash of the password (internal — never exposed in API responses)
    - `saml_idp_metadata_url` string, nullable
    - `saml_sp_entity_id` string, nullable
    - `saml_acs_url` string, nullable
    - `oidc_issuer` string, nullable
    - `oidc_client_id` string, nullable
    - `oidc_client_secret_name` string, nullable — Secrets vault key name (never stored inline)
    - `oidc_scopes` string[]
    - `jwt_jwks_url` string, nullable
    - `jwt_audience` string, nullable
    - `jwt_issuer` string, nullable
    - `api_keys` object[]
  - `build_config` BuildConfig, required — JSX build configuration for an App. Phase 1: schema only. Phase 3: used by the build pipeline Celery task.
    - `entry` string — Build entry point
    - `framework` 'react'
    - `tailwind` boolean
    - `env_vars` object — 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` object — 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` string, nullable — CDN asset prefix once deployed
  - `monitoring_config` MonitoringConfig — 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.
    - `enabled` boolean — Master switch — must be true for any monitoring to activate
    - `error_boundary_enabled` boolean — 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.
    - `sentry_enabled` boolean — Capture unhandled exceptions to Mixpeek-internal Sentry. No PII is captured (beforeSend strips it).
    - `posthog_enabled` boolean — Capture pageviews and error counts to Mixpeek-internal PostHog. No text content, no session recordings.
    - `custom_error_message` string, nullable — Custom message shown in the Error Boundary fallback UI
    - `auto_fix_enabled` boolean — When true, error spikes trigger the Claude-powered auto-fix pipeline. Requires source_files on the latest version or a connected GitHub repo.
  - `repo_url` string, nullable
  - `repo_branch` string, nullable
  - `github_installation_id` integer, nullable
  - `versions` VersionRecord[] — Deploy version history with timestamps and environment info
    - `version` integer, nullable
    - `s3_version_id` string, nullable — S3 object VersionId for instant rollback
    - `asset_prefix` string, nullable — S3 asset prefix for this version
    - `asset_manifest` object, nullable — Map of relative path → {s3_key, hash, size}
    - `asset_manifest_url` string, nullable — S3 URL of the asset manifest for this version
    - `deployed_by` string, nullable
    - `deployed_at` string, date-time, nullable
    - `environment` string
    - `build_duration_ms` integer, nullable
    - `message` string, nullable
    - `source_files` object, nullable — Map of relative path → file content for source-level version diffs
    - `git_commit_sha` string, nullable — Git commit SHA that triggered this deploy
    - `git_commit_message` string, nullable — Git commit message
    - `git_author` string, nullable — Git commit author (name <email>)
  - `environments` object, required
  - `created_at` string, date-time, nullable, required
  - `updated_at` string, date-time, nullable, required
  - `template` string, required
  - `sections` SectionConfig[], required
    - `section_id` string — Auto-generated section identifier
    - `type` string, required — Section type: 'hero', 'stats-bar', 'featured-gallery', 'search-tabs', 'results-grid', 'results-list', 'markdown-content', 'iframe-embed'
    - `props` object — Section-specific configuration properties
    - `order` integer, nullable — Explicit render order; falls back to array position if omitted
  - `custom_html` string, nullable, required
  - `hero` HeroConfig, required — Hero section configuration for a page.
    - `headline` string, required — Main headline text
    - `subheadline` string, nullable — Optional subheadline text
    - `background_type` 'image' | 'video' | 'gradient' | 'solid' — Background type
    - `background_url` string, nullable — URL for image or video background
    - `background_color` string, nullable — Background color for solid/gradient
    - `text_color` string — Hero text color
    - `logo_url` string, nullable — Logo URL displayed in hero
    - `height` string — Hero section height
    - `cta_label` string, nullable — Call-to-action button label
    - `cta_url` string, nullable — Call-to-action button URL
  - `theme` ThemeConfig, required — Theme configuration for public retriever UI. Defines colors, fonts, and visual styling for the public search interface.
    - `primary_color` string — Primary brand color (hex code)
    - `secondary_color` string, nullable — Secondary/accent color (hex code)
    - `font_family` string — Font family for text
    - `background_color` string — Background color (hex code)
    - `text_color` string — Primary text color (hex code)
    - `heading_font_family` string, nullable — Optional separate font family for headings
    - `surface_color` string, nullable — Surface/card background color (hex code)
    - `muted_color` string, nullable — Muted/secondary text color (hex code)
    - `border_color` string, nullable — Border color for cards and elements (hex code)
    - `border_radius` string, nullable — Default border radius for cards and elements
    - `card_style` string, nullable — Card visual style: elevated (shadow), flat (no shadow), bordered, or glass (frosted glass effect)
    - `card_hover_effect` string, nullable — Card hover animation effect: lift (move up), glow, scale, or none
  - `seo` SEOConfig, required — 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
    - `meta_title` string, nullable — SEO-optimized page title (50-60 chars recommended). Auto-generated from display_config.title + site_name if not provided.
    - `meta_description` string, nullable — Meta description for search engine snippets (max 160 chars). Auto-generated from display_config.description if not provided.
    - `keywords` string[] — Relevant keywords for search engines. Auto-inferred from title, description, and retriever tags.
    - `og_image_url` string, nullable — URL to OG image for social previews (1200x630px recommended). Auto-generated and uploaded to public S3 bucket during publishing.
    - `og_image_alt` string, nullable — Alt text for OG image (accessibility and SEO)
    - `og_type` string — Open Graph content type
    - `twitter_card` string — Twitter card display style
    - `twitter_site` string, nullable — Twitter @handle for the site
    - `twitter_creator` string, nullable — Twitter @handle for content creator (optional)
    - `robots` string — Robots meta directive for search engine crawlers. Use 'noindex, nofollow' to hide from search engines.
    - `canonical_url` string, nullable — Canonical URL if different from default. Auto-set to https://mxp.co/r/{public_name} if not provided.
    - `site_name` string — Site name for OG tags and branding
    - `author` string, nullable — Content author/creator name
    - `locale` string — Content language/locale
    - `logo_url` string, nullable — URL to organization/brand logo for SEO and branding. Used in structured data and can be displayed in search results.
    - `favicon_url` string, nullable — URL to favicon/icon for the public retriever page. Recommended sizes: 32x32, 48x48, or 180x180 for Apple touch icon.
    - `structured_data` StructuredDataConfig — Schema.org structured data configuration for search engines. Enables rich search results and better understanding of the page content.
      - `type` string — Schema.org type for structured data
      - `additional_properties` object — Additional Schema.org properties
  - `stats` StatItem[], required
    - `label` string, required — Stat label (e.g. 'Total Ads')
    - `value` string, required — Stat value (e.g. '12,400+')
  - `featured_gallery` FeaturedGalleryConfigOutput, required — Configuration for the featured gallery section.
    - `enabled` boolean — Whether the featured gallery is shown
    - `title` string — Gallery section title
    - `retriever_id` string, nullable — Internal retriever ID (defaults to first tab's retriever)
    - `public_name` string, nullable — Marketplace catalog public_name for gallery execution
    - `default_inputs` object — Default inputs to auto-execute when page loads
    - `layout` LayoutConfig — Layout configuration for search results display.
      - `mode` string — Display mode for results
      - `columns` integer — Number of columns for grid/masonry layouts
      - `gap` string — Gap between items
      - `full_width` boolean — Whether to use full viewport width for the layout (edge-to-edge)
    - `field_config` object — Field display configuration for gallery results
  - `tabs` PageTabOutput[], required
    - `tab_id` string, required — Unique identifier for this tab
    - `label` string, required — Display label for the tab
    - `retriever_id` string, nullable — Internal retriever ID (use for private retrievers)
    - `public_name` string, nullable — Marketplace catalog public_name (proxies execution via public API)
    - `description` string, nullable — Optional tab description shown as subtitle
    - `display_config` DisplayConfigOutput, required — 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.
      - `title` string, required — Title/heading for the public search page
      - `description` string, nullable — Optional description/subtitle for the page
      - `logo_url` string, nullable — URL to logo image
      - `icon_base64` string, nullable — 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...'
      - `seo` SEOConfig — 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
        - `meta_title` string, nullable — SEO-optimized page title (50-60 chars recommended). Auto-generated from display_config.title + site_name if not provided.
        - `meta_description` string, nullable — Meta description for search engine snippets (max 160 chars). Auto-generated from display_config.description if not provided.
        - `keywords` string[] — Relevant keywords for search engines. Auto-inferred from title, description, and retriever tags.
        - `og_image_url` string, nullable — URL to OG image for social previews (1200x630px recommended). Auto-generated and uploaded to public S3 bucket during publishing.
        - `og_image_alt` string, nullable — Alt text for OG image (accessibility and SEO)
        - `og_type` string — Open Graph content type
        - `twitter_card` string — Twitter card display style
        - `twitter_site` string, nullable — Twitter @handle for the site
        - `twitter_creator` string, nullable — Twitter @handle for content creator (optional)
        - `robots` string — Robots meta directive for search engine crawlers. Use 'noindex, nofollow' to hide from search engines.
        - `canonical_url` string, nullable — Canonical URL if different from default. Auto-set to https://mxp.co/r/{public_name} if not provided.
        - `site_name` string — Site name for OG tags and branding
        - `author` string, nullable — Content author/creator name
        - `locale` string — Content language/locale
        - `logo_url` string, nullable — URL to organization/brand logo for SEO and branding. Used in structured data and can be displayed in search results.
        - `favicon_url` string, nullable — URL to favicon/icon for the public retriever page. Recommended sizes: 32x32, 48x48, or 180x180 for Apple touch icon.
        - `structured_data` StructuredDataConfig — Schema.org structured data configuration for search engines. Enables rich search results and better understanding of the page content.
          - `type` string — Schema.org type for structured data
          - `additional_properties` object — Additional Schema.org properties
      - `markdowns` MarkdownContent[] — 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.
        - `title` string, required — Title for the markdown content section
        - `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.
      - `theme` ThemeConfig — Theme configuration for public retriever UI. Defines colors, fonts, and visual styling for the public search interface.
        - `primary_color` string — Primary brand color (hex code)
        - `secondary_color` string, nullable — Secondary/accent color (hex code)
        - `font_family` string — Font family for text
        - `background_color` string — Background color (hex code)
        - `text_color` string — Primary text color (hex code)
        - `heading_font_family` string, nullable — Optional separate font family for headings
        - `surface_color` string, nullable — Surface/card background color (hex code)
        - `muted_color` string, nullable — Muted/secondary text color (hex code)
        - `border_color` string, nullable — Border color for cards and elements (hex code)
        - `border_radius` string, nullable — Default border radius for cards and elements
        - `card_style` string, nullable — Card visual style: elevated (shadow), flat (no shadow), bordered, or glass (frosted glass effect)
        - `card_hover_effect` string, nullable — Card hover animation effect: lift (move up), glow, scale, or none
      - `inputs` InputRenderingConfigOutput[], 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.
        - `field_name` string, required — Name of the input field (matches retriever input_schema key)
        - `field_schema` RetrieverInputSchemaFieldOutput, required — 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)
          - `type` 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'object' | 'array' | 'date' | 'datetime' | 'text' | 'image' | 'audio' | 'video' | 'pdf' | 'excel' | 'document_reference', required — 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.
          - `default` unknown
          - `items` RetrieverInputSchemaFieldOutput — recursive
          - `properties` object, nullable
          - `examples` unknown[], nullable — OPTIONAL. List of example values for this field. Used by Apps to show example inputs in the UI. Provide multiple diverse examples when possible.
            - unknown
          - `description` string, nullable
          - `enum` unknown[], nullable
            - unknown
          - `required` boolean, nullable
        - `input_type` string — UI input component type. Determines how the input is rendered: text (single line), select (dropdown), file (upload), multiselect (multiple choice)
        - `label` string, required — Human-readable label for the input
        - `placeholder` string, nullable — Placeholder text for the input
        - `helper_text` string, nullable — Helper text displayed below the input to guide users
        - `suggestions` string[], nullable — Pre-filled suggestion chips that users can click to populate the input
        - `required` boolean — Whether this input is required
        - `order` integer — Display order (lower numbers appear first)
      - `layout` LayoutConfig — Layout configuration for search results display.
        - `mode` string — Display mode for results
        - `columns` integer — Number of columns for grid/masonry layouts
        - `gap` string — Gap between items
        - `full_width` boolean — Whether to use full viewport width for the layout (edge-to-edge)
      - `exposed_fields` string[], required — List of document metadata fields to show in results. Only these fields are returned to end users.
      - `components` ComponentsConfig — Configuration for UI components.
        - `show_hero` boolean — Whether to show the hero section with title and description
        - `show_search` boolean — Whether to show search input fields
        - `show_filters` boolean — Whether to show filters sidebar
        - `show_results_header` boolean — Whether to show the results header with count and sorting options
        - `result_layout` string — Layout mode for results display
        - `result_card` ResultCardProperties — Properties for result card display configuration.
          - `layout` string — Card layout orientation
          - `show_thumbnail` boolean — Whether to show thumbnail image in results
          - `thumbnail_aspect_ratio` string — Aspect ratio for thumbnail images
          - `thumbnail_fit` string — How thumbnail should fit in container
          - `show_score` boolean — Whether to display relevance score
          - `truncate_title` integer, nullable — Maximum characters for title before truncation
          - `truncate_description` integer, nullable — Maximum characters for description before truncation
          - `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.
          - `show_find_similar` boolean — Whether to show a 'Find Similar' button on result cards
          - `card_click_action` string — Action when card is clicked: none (no action), findSimilar (trigger similar search), viewDetails (open detail modal)
          - `thumbnail_field` string, nullable — Field name to use as thumbnail image source
          - `title_field` string, nullable — Field name to use as card title
          - `card_fields` string[], nullable — Fields to display on the card (alternative to field_order for template compatibility)
          - `modal_fields` string[], nullable — Fields to display in the detail modal when card is clicked
          - `card_style` string, nullable — Card style preset: default, portrait-discovery, media-search, document-search, or custom template-specific styles
      - `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.
      - `custom_cta` CustomCTA — 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.
        - `label` string, required — Button label text displayed in the header
        - `markdown_content` string, required — Markdown content displayed in the modal when button is clicked. Supports standard markdown syntax.
      - `external_links` ExternalLink[] — External resource links for this retriever (GitHub repos, blog posts, docs, etc.). Displayed on homepage and retriever listing pages to provide additional context.
        - `name` string, required — Display name for the link
        - `url` string, required — URL to the external resource
      - `template_type` string, nullable — Template identifier for frontend rendering. Built-in templates: portrait-gallery, media-search, document-search. Custom templates can use any string identifier.
      - `field_mappings` object, nullable — 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.
      - `extensions` object, nullable — Generic extensions for template-specific configuration. Allows templates to store custom config without schema changes.
      - `retriever_config` object, nullable — Embedded retriever configuration (stages, feature extractors) for the View Config modal. Auto-populated at publish time.
  - `password_protected` boolean, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)